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 種 產生影片的方式:
- 傳送文字 → 產生影片
- 傳送文字 + 上傳圖片 → 使用他們的圖片產生影片
- 傳送文字 + 圖片網址 → 使用網址中的圖片產生影片
代理程式會靜默處理其他所有事項。
重要提示:在啟動產生任務前,立即回覆使用者一個確認訊息,例如: "🎬 正在開始產生影片——我將在 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:文字 + 圖片網址
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. 從網址(圖片已有公開網址)
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 → 註冊),而非基於網址的上傳。
觸發條件: 僅在使用者明確要求產生影片並在同一訊息中傳送圖片附件時(例如「用這張照片製作影片」)。請勿自動上傳每張圖片訊息——其他技能或對話可能涉及與影片產生無關的圖片。
# 從本地檔案(由 OpenClaw 從附件下載)
python3 {baseDir}/scripts/medeo_video.py upload-file \
--file /tmp/user_photo.jpg
# 從直接網址(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 |
| 飛書 | 來自訊息內容 JSON 的 message_id + image_key | --feishu-message-id + --feishu-image-key |
下載附件二進位制 → 儲存到 /tmp | --file | |
| 通用網址 | 任何直接圖片網址 | --url |
注意: Discord 附件網址是公開的 CDN 連結——可直接使用 --url。所有其他平台都需要驗證才能下載。
3c. 在產生管道中內聯
# 基於網址(現有行為)
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" | 從公開網址上傳 | 否(代理程式內部) |
upload-file --file PATH | 從本地檔案上傳 | 否(代理程式內部) |
upload-file --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傳遞給產生命令。如果使用者已傳送圖片,切勿要求他們提供網址。 - IM 原生傳送 —— 產生後,使用 IM 頻道的原生方法傳送影片(不僅僅是網址)。每個頻道都有專用的傳送腳本:
- 飛書:
python3 {baseDir}/scripts/feishu_send_video.py --video /tmp/result.mp4 --to "oc_xxx_or_ou_xxx" --cover-url "<縮圖網址>" --duration <毫秒>(群組聊天使用oc_chat_id,私人聊天使用ou_open_id;也接受chat:oc_xxx和user:ou_xxx前綴形式) - Telegram:下載影片,然後透過
telegram_send_video.py傳送(token 僅從環境變數取得):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>" \
- 飛書:
...
[已截斷以進行翻譯]