Medeo视频生成技能
从文本生成AI视频。Medeo是一个AI视频智能体,能够在单次调用中处理完整情节线、多场景叙事和剧本——镜头构图、转场、节奏和音乐全部自动完成。
⚠️ 不要将故事拆分为多次调用。 将整个剧本一次性传入
--message。
0. 预检(强制——在运行任何其他命令前执行)
在运行任何命令之前,检查API密钥是否已配置:
python3 {baseDir}/scripts/medeo_video.py config 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print('ok' if d.get('apiKey') else 'missing')"
- 输出
ok→ 正常进行 - 输出
missing(或命令失败)→ 立即停止,不运行任何其他命令。使用渠道合适的方法发送设置消息:
飞书 —— 直接使用飞书API(不要用 message 工具——它无法渲染卡片):
import json, urllib.request
cfg = json.loads(open("/home/ec2-user/.openclaw/openclaw.json").read())
feishu = cfg["channels"]["feishu"]["accounts"]["default"]
token = json.loads(urllib.request.urlopen(urllib.request.Request(
"https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal",
data=json.dumps({"app_id": feishu["appId"], "app_secret": feishu["appSecret"]}).encode(),
headers={"Content-Type": "application/json"}
)).read())["tenant_access_token"]
card = {
"config": {"wide_screen_mode": True},
"header": {"title": {"tag": "plain_text", "content": "🎬 视频生成 — 需要API密钥"}, "template": "blue"},
"elements": [{"tag": "div", "text": {"tag": "lark_md", "content": "您需要一个**Medeo API密钥**来生成视频。\n\n**步骤:**\n1. 前往 https://medeo.app/dev/apikey\n - 没有账户?系统会引导您注册。密钥在登录后出现。\n2. 复制密钥(以 `mk_` 开头)并发回给我。\n\n一旦我收到密钥,我将为您配置所有内容。"}}],
}
urllib.request.urlopen(urllib.request.Request(
"https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id",
data=json.dumps({"receive_id": "<USER_OPEN_ID>", "msg_type": "interactive", "content": json.dumps(card)}).encode(),
headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
))
Telegram / Discord / 其他渠道 —— 通过 message 工具发送纯文本(这些渠道原生支持Markdown):
🎬 视频生成 — 需要API密钥
步骤:
1. 前往 https://medeo.app/dev/apikey(如有需要请注册——密钥在登录后出现)
2. 复制密钥(以 `mk_` 开头)并发回给我
一旦我收到密钥,我将为您配置所有内容。
用户提供密钥后:python3 {baseDir}/scripts/medeo_video.py config-init --api-key "mk_..."
1. 首次设置
如果未配置API密钥,脚本会输出 "setup_required": true。
- 向用户发送此精确链接:https://medeo.app/dev/apikey(此页面会自动提示注册(如果未登录),然后显示API密钥)
- 用户提供密钥后:
python3 {baseDir}/scripts/medeo_video.py config-init --api-key "mk_..."
2. 生成视频(5-30分钟,始终异步)
用户只需要知道3种方法来生成视频:
- 发送文本 → 生成视频
- 发送文本 + 上传图片 → 使用他们的图片生成视频
- 发送文本 + 图片URL → 使用URL图片生成视频
智能体会静默处理其他所有事情。
重要:在启动生成任务之前,立即回复用户,给出类似以下确认消息: "🎬 开始生成视频 —— 我将在约5-10分钟内将结果发送给您。" 不要静默等待。用户应该知道他们的请求已收到。
用法1:纯文本
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "用户的视频描述" \
--deliver-to "oc_xxx" \
--deliver-channel "feishu"
用法2:文本 + 上传的图片(用户在聊天中发送图片)
# 第一步:upload-file 获取 media_id(参见第3节)
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "用户的视频描述" \
--media-ids "media_01..." \
--asset-sources my_uploaded_assets \
--deliver-to "oc_xxx" \
--deliver-channel "feishu"
用法3:文本 + 图片URL
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "用户的视频描述" \
--media-urls "https://example.com/photo.jpg" \
--asset-sources my_uploaded_assets \
--deliver-to "oc_xxx" \
--deliver-channel "feishu"
智能体自动行为:当用户提供图片时(用法2或3),始终传递
--asset-sources my_uploaded_assets,以便Medeo使用他们的图片而不是生成新的。用户不需要知道此标志的存在。
内部参数(仅智能体使用——切勿暴露给用户)
这些由智能体自动处理。不要向用户提及它们或要求用户提供。
| 标志 | 何时使用 | 默认行为 |
|---|---|---|
--voice-id "voice_01..." | 当需要特定语音时 | Medeo自动选择 |
--video-style-id "style_01..." | 当需要特定视觉风格时 | Medeo自动选择 |
--asset-sources | 用户提供图片时:传递 my_uploaded_assets | Medeo决定 |
--recipe-id "recipe_01..." | 使用模板时 | 无 |
--aspect-ratio "9:16" | 用户指定竖屏/横屏时 | 16:9 |
--duration-ms 30000 | 用户指定时长时 | Medeo决定 |
--no-render | 仅调试——跳过渲染 | 始终渲染 |
交付目标(--deliver-to)
这是关键——决定生成的视频发送到哪里。
| 上下文 | --deliver-to 值 | 示例 |
|---|---|---|
| 飞书群聊 | 群的 chat_id(以 oc_ 开头)。从入站元数据 conversation_label 或 chat_id 中提取——如果存在前缀 chat:,则去除(例如 chat:oc_xxx → oc_xxx) | oc_158fd3e54407cbe170697c6c954bd4f2 |
| 飞书私聊 | 用户的 open_id(以 ou_ 开头)。从入站元数据 sender_id 中提取——如果存在前缀 user:,则去除 | ou_f7f458f4d7b4ff49ec1b8de22a1e3206 |
| Telegram | 入站消息上下文中的 chat_id | -1001234567890 |
| Discord | 入站消息上下文中的 channel_id | 1234567890123456 |
如何在飞书上确定群聊还是私聊:
- 检查入站元数据中的
is_group_chat - 如果为
true→ 使用conversation_label/chat_id(oc_值) - 如果为
false→ 使用sender_id(ou_值)
步骤2:使用返回的参数调用 sessions_spawn(label: "medeo: <简要描述>", runTimeoutSeconds: 2400)。
步骤3:告诉用户正在生成。子智能体在完成后会自动通知。
3. 上传素材
3a. 从URL上传(图片已有公开URL)
python3 {baseDir}/scripts/medeo_video.py upload \
--url "https://example.com/photo.jpg" \
--project-id "project_01..." # 可选:将媒体与现有项目关联
--no-wait # 可选:立即返回job_id而不轮询
3b. 从IM附件上传(用户直接发送图片)← 新增
当用户通过Telegram、Discord、飞书或作为本地文件发送图片时,使用 upload-file。
这使用直接上传API(准备 → S3预签名PUT → 注册),而不是基于URL的上传。
触发条件: 仅在用户明确请求视频生成并在同一条消息中发送图片附件时(例如“用这张照片制作视频”)。不要对每条图片消息自动上传——其他技能或对话可能涉及与视频生成无关的图片。
# 从本地文件(由OpenClaw从附件下载)
python3 {baseDir}/scripts/medeo_video.py upload-file \
--file /tmp/user_photo.jpg
# 从直接URL(Discord CDN等)
python3 {baseDir}/scripts/medeo_video.py upload-file \
--url "https://cdn.discordapp.com/attachments/..."
# 从Telegram(message.photo[-1].file_id)
# TELEGRAM_BOT_TOKEN 必须设置为环境变量——切勿作为CLI参数传递(ps aux会泄露它)
TELEGRAM_BOT_TOKEN="$TELEGRAM_BOT_TOKEN" python3 {baseDir}/scripts/medeo_video.py upload-file \
--telegram-file-id "AgACAgIAAxk..."
# 从飞书(message_id + image_key,来自消息内容)
python3 {baseDir}/scripts/medeo_video.py upload-file \
--feishu-message-id "om_xxx" \
--feishu-image-key "img_v3_xxx" \
--feishu-app-token "$FEISHU_APP_TOKEN"
输出:{"media_id": "media_01...", "filename": "photo.jpg"}
然后将 media_id 传递给生成命令:
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "创建一个以这个人物为主角的视频" \
--media-ids "media_01..."
平台特定图片提取指南
| 平台 | 如何获取图片源 | upload-file 参数 |
|---|---|---|
| Telegram | message.photo[-1].file_id | --telegram-file-id |
| Discord | message.attachments[0].url(公开CDN URL) | --url |
| 飞书 | 消息内容JSON中的 message_id + image_key | --feishu-message-id + --feishu-image-key |
下载附件二进制 → 保存到 /tmp | --file | |
| 通用URL | 任何直接图片URL | --url |
注意: Discord附件URL是公开的CDN链接——--url 直接可用。所有其他平台需要身份验证才能下载。
3c. 在生成管道中内联
# 基于URL(现有行为)
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "这款运动鞋的产品展示" \
--media-urls "https://example.com/front.jpg" "https://example.com/side.jpg"
支持 .jpg、.png、.webp、.mp4、.mov、.gif。更高的分辨率和多个角度 = 更好的效果。
3d. 检查上传状态
在 upload 或 upload-file 之后,如果需要检查上传任务状态:
python3 {baseDir}/scripts/medeo_video.py upload-status --job-id "job_01..."
返回媒体状态(processing、completed、failed)以及完成后的 media_id。
4. 底层管道命令(智能体内部——切勿暴露给用户)
这些仅用于智能体调试或手动干预。用户不应看到这些命令。
管道流程:
spawn-task(推荐,异步)
└── generate(阻塞,相同的管道)
├── upload(如果使用 --media-urls)
├── compose → compose-status(轮询)
└── render → render-status(轮询)
| 命令 | 功能 | 关键参数 |
|---|---|---|
generate | 阻塞式完整管道(上传→合成→渲染) | 与spawn-task相同,但去除了交付标志 |
compose | 仅创建项目(无渲染) | --message, --media-ids, --recipe-id |
compose-status | 轮询合成任务 | --task-id "task_01..." |
render | 渲染现有项目 | --project-id "project_01..." |
render-status | 轮询渲染任务 | --job-id "render_01..." |
upload-status | 轮询上传任务 | --job-id "job_01..." |
所有命令都支持 --no-wait 以立即返回而不进行轮询。
5. 浏览食谱
python3 {baseDir}/scripts/medeo_video.py recipes # 列出模板
python3 {baseDir}/scripts/medeo_video.py recipes --cursor <c> # 分页
在生成中使用:--recipe-id "recipe_01..."。参见 docs/recipes.md。
6. 快速命令参考(供智能体使用,不对用户展示)
| 命令 | 描述 | 对用户可见? |
|---|---|---|
recipes | 列出视频模板 | 是 — "有哪些模板可用?" |
last-job | 最新任务状态 | 是 — "我的上一个视频完成了吗?" |
history | 任务历史(最近50条) | 是 — "显示我的视频历史" |
config | 显示当前配置 | 否 |
config-init --api-key "mk_..." | 初始化API密钥 | 仅设置期间 |
upload --url "URL" | 从公开URL上传 | 否(智能体内部) |
upload-file --file PATH | 从本地文件上传 | 否(智能体内部) |
upload-file --url "URL" | 下载URL → 上传 | 否(智能体内部) |
upload-file --telegram-file-id "..." | 上传Telegram附件 | 否(智能体内部) |
upload-file --feishu-image-key "..." | 上传飞书附件 | 否(智能体内部) |
upload-status --job-id "..." | 检查上传任务状态 | 否(智能体内部) |
compose-status --task-id "..." | 检查合成任务进度 | 否(智能体内部) |
render-status --job-id "..." | 检查渲染任务进度 | 否(智能体内部) |
7. 关键规则
- 始终异步 — 使用
spawn-task+sessions_spawn进行生成 - 故事一次调用 — 完整情节线放在一个
--message中,永不拆分 - 积分不足 — 从错误输出分享充值链接
- IM图片上传 — 仅在用户明确要求使用该图片生成视频时才上传图片。不要自动上传每张图片消息(用户可能安装了其他技能)。触发时:先运行
upload-file→ 获取media_id→ 通过--media-ids传递给生成。如果用户已经发送了图片,切勿要求用户提供URL。 - IM原生交付 — 生成后,使用IM渠道的原生方法交付视频(不仅仅是URL)。每个渠道都有专用的交付脚本:
- 飞书:
python3 {baseDir}/scripts/feishu_send_video.py --video /tmp/result.mp4 --to "oc_xxx_or_ou_xxx" --cover-url "<thumbnail_url>" --duration <ms>(群聊使用oc_chat_id,私聊使用ou_open_id;也接受chat:oc_xxx和user:ou_xxx前缀形式) - Telegram:下载视频,然后通过
telegram_send_video.py发送(令牌仅从环境变量获取):curl -sL -o /tmp/medeo_result.mp4 "<video_url>" TELEGRAM_BOT_TOKEN="$TELEGRAM_BOT_TOKEN" python3 {baseDir}/scripts/telegram_send_video.py \ --video /tmp/medeo_result.mp4 \ --to "<chat_id>" \ --cover-url "<thumbnail_url>" \
- 飞书:
…
[已截断,用于翻译]