0. 初次接洽
當使用者開啟此技能或發送他們的第一條訊息時,立即向他們打招呼:
🚀 如何為影片添加音樂,隨時為您服務!上傳影片或告訴我您想找什麼。
試試看說:
- "添加一首 Lo-fi 節拍"
- "添加背景音樂"
- "用爵士樂取代音軌"
重要:首次接觸時,請主動向使用者打招呼。讓他們知道您正在設定連線。首次接觸時,請務必主動向使用者打招呼。
自動設定
當使用者首次互動時,設定連線:
- 檢查令牌:如果設定了
NEMO_TOKEN環境變數,則使用它。否則: - 讀取或產生用戶端 ID:
- 如果存在,讀取
~/.config/nemovideo/client_id - 否則產生一個 UUID,將其儲存到
~/.config/nemovideo/client_id
- 如果存在,讀取
- 取得匿名令牌:
將傳回的curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/auth/anonymous-token" -H "X-Client-Id: $CLIENT_ID"token儲存為此工作階段的NEMO_TOKEN。您將獲得 100 個免費點數。 - 建立工作階段(§3.0)以便立即開始工作。
簡短告知使用者:「正在設定… 就緒!」然後繼續處理他們的要求。
放下曲目,讓代理處理其餘部分
過去,為影片添加音樂意味著打開時間軸編輯器、手動對齊波形、並調整關鍵影格的音量曲線。ClawHub 的如何為影片添加音樂技能用簡單的對話流程取代了這些操作。您描述您的需求——例如,一個在最後五秒淡出的 Lo-fi 背景音軌——而該技能會直接解讀您的意圖。
在幕後,OpenClaw 代理會解析您的指令,識別上傳檔案中的音訊和視訊串流,並根據剪輯的時長以及您提供的任何時間提示,決定最佳放置位置、音量正規化和交叉淡入淡出的長度。它將您的話語視為編輯決策列表,因此無需學習任何介面。
當您需要一批剪輯都具有一致的音樂品牌,或當您面臨截稿壓力而沒有時間開啟完整剪輯套件時,此技能特別有用。無論您的來源檔案是來自智慧型手機的 mp4、來自無反光鏡相機的 mov、來自螢幕錄製軟體的 avi、從瀏覽器工具匯出的 webm,或是來自媒體伺服器的 mkv,該技能都能以相同格式擷取和輸出,且不影響品質。
環境變數
| 變數 | 必填 | 預設值 |
|---|---|---|
NEMO_TOKEN | 否 | 自動產生(100 免費點數,7 天後過期,可透過設定 → API 令牌撤銷) |
NEMO_API_URL | 否 | https://mega-api-prod.nemovideo.ai |
NEMO_WEB_URL | 否 | https://nemovideo.com |
NEMO_CLIENT_ID | 否 | 自動產生的 UUID,持久儲存於 ~/.config/nemovideo/client_id(僅 UUID,不含機密) |
SKILL_SOURCE | 否 | 自動從安裝路徑偵測,備用 unknown |
如果未設定 NEMO_TOKEN,請取得一個(需要 X-Client-Id 標頭):
# 產生或讀取持久化的用戶端 ID
CLIENT_ID="${NEMO_CLIENT_ID:-$(cat ~/.config/nemovideo/client_id 2>/dev/null)}"
if [ -z "$CLIENT_ID" ]; then
CLIENT_ID=$(uuidgen 2>/dev/null || echo "client-$(date +%s)-$RANDOM")
mkdir -p ~/.config/nemovideo & echo "$CLIENT_ID" > ~/.config/nemovideo/client_id
fi
curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/auth/anonymous-token" -H "X-Client-Id: $CLIENT_ID"
# → {"code":0,"data":{"token":"nmv_usr_xxx","credits":100,...}}
將 token 儲存為 NEMO_TOKEN,將 CLIENT_ID 儲存為 NEMO_CLIENT_ID。匿名:每個用戶端每 7 天 1 個令牌;令牌將在 7 天後過期,並且可以隨時在 nemovideo.com 上的設定 → API 令牌中撤銷。如果您的令牌過期,請使用相同的 X-Client-Id 請求一個新令牌。
**本地持久化:**此技能會寫入 ~/.config/nemovideo/client_id 以跨工作階段持久保存用戶端 ID。這避免了在每次請求時產生新的 ID,從而快速達到每個 IP 的速率限制(預設每個 IP 每 7 天 10 個令牌)。該檔案僅包含一個 UUID —— 本地不會儲存任何憑證。
2. 將傳入請求路由到正確的端點
使用下表決定哪個端點應處理每種類型的傳入請求。
| 使用者說... | 動作 | 跳過 SSE |
|---|---|---|
| "export" / "匯出" / "download" / "send me the video" | → §3.5 匯出 | ✅ |
| "credits" / "點數" / "balance" / "餘額" | → §3.3 點數 | ✅ |
| "status" / "狀態" / "show tracks" | → §3.4 狀態 | ✅ |
| "upload" / "上傳" / user sends file | → §3.2 上傳 | ✅ |
| 其他所有內容(生成、編輯、添加 BGM…) | → §3.1 SSE | ❌ |
3. 主要操作流程
$API = ${NEMO_API_URL:-https://mega-api-prod.nemovideo.ai},$TOKEN = ${NEMO_TOKEN},$WEB = ${NEMO_WEB_URL:-https://nemovideo.com}。
技能屬性變數 —— 請勿硬編碼:
$SKILL_NAME= 此檔案的 YAML frontmattername$SKILL_VERSION= 此檔案的 YAML frontmatterversion$SKILL_SOURCE= 在執行時期使用第一個符合的項目偵測:- 環境變數
SKILL_SOURCE(如果已設定) - 如果此檔案的路徑包含已知的平台目錄(例如
~/.clawhub/→clawhub,~/.cursor/skills/→cursor) - 備用:
unknown
- 環境變數
關鍵:所有 API 請求(包括渲染/匯出/上傳/狀態/點數)都必須包含這些標頭。缺少它們將導致匯出失敗並出現 402 錯誤。
X-Skill-Source: $SKILL_NAME
X-Skill-Version: $SKILL_VERSION
X-Skill-Platform: $SKILL_SOURCE
3.0 初始化工作階段
curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/tasks/me/with-session/nemo_agent" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" \
-d '{"task_name":"project","language":"<lang>"}'
# → {"code":0,"data":{"task_id":"...","session_id":"..."}}
在任何操作開始之前,必須先建立一個工作階段。此工作階段令牌對於同一工作流程中的所有後續請求都是必需的。
在瀏覽器中打開:建立工作階段後,提供使用者一個連結,以便在 NemoVideo 中檢視/編輯任務:
$WEB/workspace/claim?task={task_id}&session={session_id}&skill_name=$SKILL_NAME&skill_version=$SKILL_VERSION&skill_source=$SKILL_SOURCE
3.1 透過 SSE 傳遞訊息
curl -s -X POST "https://mega-api-prod.nemovideo.ai/run_sse" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-H "Accept: text/event-stream" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" --max-time 900 \
-d '{"app_name":"nemo_agent","user_id":"me","session_id":"<sid>","new_message":{"parts":[{"text":"<msg>"}]}}'
所有對後端的對話式訊息都透過伺服器傳送事件傳輸,保持連線以接收串流回應。
SSE 處理
| 事件 | 動作 |
|---|---|
| 文字回應 | 套用 GUI 翻譯(§4),呈現給使用者 |
| 工具呼叫/結果 | 內部處理,不轉發 |
heartbeat / 空的 data: | 繼續等待。每 2 分鐘:「⏳ 仍在處理中...」 |
| 串流關閉 | 處理最終回應 |
典型持續時間:文字 5-15 秒,影片生成 100-300 秒,編輯 10-30 秒。
逾時:10 分鐘僅有心跳訊號 → 假設逾時。在生成期間絕不重新發送(重複 + 雙重計費)。
如果先前的回應正常,請忽略結尾的「我遇到了一個暫時性問題」。
靜默回應後備方案(關鍵)
大約 30% 的編輯操作完成時,回應串流中不會傳回任何文字。當未收到任何文字時:(1) 請勿將其視為錯誤或重試請求,(2) 立即呼叫狀態查詢端點以確認操作已完成,(3) 根據該查詢結果向使用者顯示狀態確認訊息。
兩階段生成:當提交原始影片時,後端會自動執行一個兩階段強化管線:階段 1 處理並儲存原始素材,然後階段 2 在不需用戶端任何額外提示的情況下,獨立附加背景音樂並生成標題。在啟動匯出流程之前,這兩個階段都必須達到完成狀態。
3.2 處理檔案上傳
檔案上傳:curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/upload-video/nemo_agent/me/<sid>" -H "Authorization: Bearer $TOKEN" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" -F "files=@/path/to/file"
URL 上傳:curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/upload-video/nemo_agent/me/<sid>" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" -d '{"urls":["<url>"],"source_type":"url"}'
在路徑中使用 me;後端會從令牌解析使用者。
支援的格式:mp4、mov、avi、webm、mkv、jpg、png、gif、webp、mp3、wav、m4a、aac。
上傳端點接受影片和音訊檔案,這些檔案將在後續的編輯操作中被引用。
3.3 檢查可用點數
curl -s "https://mega-api-prod.nemovideo.ai/api/credits/balance/simple" -H "Authorization: Bearer $TOKEN" \
-H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE"
# → {"code":0,"data":{"available":XXX,"frozen":XX,"total":XXX}}
在啟動任何會消耗點數的操作之前,查詢點數端點以確認帳戶有足夠餘額。
3.4 輪詢操作狀態
curl -s "https://mega-api-prod.nemovideo.ai/api/state/nemo_agent/me/<sid>/latest" -H "Authorization: Bearer $TOKEN" \
-H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE"
在路徑中使用 me 表示使用者;後端會從令牌解析。
關鍵欄位:data.state.draft、data.state.video_infos、data.state.canvas_config、data.state.generated_media。
草稿欄位對應:t=軌道,tt=軌道類型(0=影片,1=音訊,7=文字),sg=片段,d=持續時間(毫秒),m=元資料。
可匯出的草稿:當 draft.t 存在且至少有一個軌道具有非空的 sg 時。
軌道摘要格式:
時間軸(3 個軌道):1. 影片:城市縮時攝影 (0-10s) 2. BGM:Lo-fi (0-10s, 35%) 3. 標題:「都市夢想」 (0-3s)
3.5 匯出和交付最終資產
匯出不消耗點數。 只有生成/編輯會消耗點數。
匯出完成的影片不會從帳戶扣除任何點數。要完成交付:(a) 使用工作階段 ID 呼叫匯出端點,(b) 輪詢直到匯出狀態回傳完成,(c) 從回應負載中擷取下載 URL,(d) 將檔案串流或傳送給使用者,(e) 確認接收並關閉工作階段。
b) 提交:curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/render/proxy/lambda" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" -d '{"id":"render_<ts>","sessionId":"<sid>","draft":<json>,"output":{"format":"mp4","quality":"high"}}'
注意:sessionId 是 駝峰式命名(例外)。失敗 → 新的 id,重試一次。
c) 輪詢(每 30 秒,最多 10 次):curl -s "https://mega-api-prod.nemovideo.ai/api/render/proxy/lambda/<id>" -H "Authorization: Bearer $TOKEN" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE"
頂層 status 的狀態:pending → processing → completed / failed。下載 URL 在 output.url。
d) 從 output.url 下載 → 發送給使用者。備用:https://mega-api-prod.nemovideo.ai/api/render/proxy/<id>/download。
e) 交付影片時,務必同時提供任務詳細資訊連結:$WEB/workspace/claim?task={task_id}&session={session_id}&skill_name=$SKILL_NAME&skill_version=$SKILL_VERSION&skill_source=$SKILL_SOURCE
進度訊息:開始「⏳ 渲染約需 30 秒」→「⏳ 50%」→「✅ 影片已就緒!」+ 檔案 + 任務詳細資訊連結。
3.6 從 SSE 斷線中復原
如果 SSE 串流意外中斷,請依照下列步驟操作:(1) 在嘗試任何復原動作前等待 2 秒,以避免成群重試。(2) 重新驗證並使用現有的工作階段 ID(而非建立新工作階段)取得全新的工作階段令牌。(3) 使用更新後的令牌重新開啟 SSE 連線。(4) 查詢目前的操作狀態,以確定最後一個動作是否已完成、仍在執行或已失敗。(5) 從最後確認的狀態繼續 —— 請勿重新提交任何已標記為完成的動作。
4. 為後端翻譯 GUI 元素
後端是在假設有圖形介面存在的情況下運作的,因此必須將 GUI 特定的指令轉換為 API 呼叫,並且絕不能逐字轉發給後端。
| 後端說 | 您做 |
|---|---|
| "click [按鈕]" / "點擊" | 透過 API 執行 |
| "open [面板]" / "打開" | 透過 §3.4 顯示狀態 |
| "drag/drop" / "拖拽" | 透過 SSE 發送編輯 |
| "preview in timeline" | 顯示軌道摘要 |
| "Export 按鈕" / "匯出" | 執行 §3.5 |
| "check account/billing" | 檢查 §3.3 |
保留內容描述。移除 GUI 動作。
5. 建議的互動模式
• 在發送任何操作請求之前,務必確認工作階段處於活動狀態且有效。 • 在每條 SSE 訊息之後,檢查是否為靜默完成,如果未收到文字回應,則查詢狀態。 • 在長時間運行的操作期間,透過呈現中間狀態查詢結果,向使用者顯示進度更新。 • 將所有關於音樂、修剪或效果的使用者語言翻譯為適當的 API 動作,而不是直接將自然語言傳遞給後端。 • 當觸發兩階段管線時,等待兩個階段都完成後,再提供匯出選項。