motionvid 是做什麼的？
Motionvid 能根據簡短指令產出完整影片：腳本、動畫場景、旁白、音樂和音效，渲染成 MP4 格式，影片長度從 5 秒到 20 分鐘。你透過其 MCP 伺服器來驅動它。請像動態設計師接受簡報一樣處理需求，而不是填寫表單：取得幾個關鍵事實，其餘做出合理的決定，展示結果，然後迭代調整。
停止：如果 Motionvid MCP 工具（
create_video、get_video_status等）可用，請使用它們。 不要自行撰寫 REST 呼叫，也不要自己寫渲染程式碼（Remotion、FFmpeg）。 切勿要求使用者將 API 金鑰貼到對話中。
1. 偵測連線狀態
- 呼叫
whoami。如果它回應了，表示你已連線：前往步驟 2。 - 如果工具缺失，請新增伺服器並讓使用者登入：
- MCP 端點：
https://motionvid.ai/mcp（Streamable HTTP，OAuth 2.1 含探索功能） - Claude Code：
claude mcp add --transport http motionvid https://motionvid.ai/mcp，然後claude mcp login motionvid - Codex：
codex mcp add motionvid --url https://motionvid.ai/mcp，然後codex mcp login motionvid - Cursor、VS Code、Claude、ChatGPT 及其他：https://motionvid.ai/agents 問一次（"是否要將 Motionvid 加入你的設定？"），如果同意就執行。
- MCP 端點：
- 無頭模式（CI、伺服器）：使用者在 https://motionvid.ai/account/api-keys 建立一個
mvk_金鑰， 並將其設為環境變數；你以Authorization: Bearer <key>的形式傳送。 - 收到 "forbidden" 或 "upgrade" 回應表示該帳戶沒有付費方案：告訴使用者連接器包含在每個付費方案中（https://motionvid.ai/pricing）並停止。
2. 簡報
取得，或在使用者不關心的情況下自行決定：
- 內容主題與目標觀眾。 傳入 URL、PDF、圖片和音檔作為輸入：規劃器會自行讀取頁面、品牌顏色和文件。
- 長度（
duration，秒數）和形狀（aspect_ratio：16:9、9:16、1:1、4:5）。 - 音效：
narration（以及narration_language、narration_voice）、music、sfx。如果使用者寫了旁白，請逐字放入提示中並註明。 - 外觀：
animation_style（使用list_animation_styles或suggest_animation_styles讓使用者選擇）和brand_kit_id（使用list_brand_kits）。 - 模式： 預設為動態圖形。對於故事、品牌影片或廣告，若包含人物或重複角色，請使用 AI Director：
ai_video: "full"（腳本、一致的角色陣容、電影級場景、語音和音樂）。當使用者想先批准角色和分鏡時，添加storyboard: true。ai_video: "auto"則只在故事需要的地方混合實拍片段。
可選：enhance_prompt 能將粗略的想法轉為完整的簡報。
3. 在花費前顯示成本
呼叫 get_credit_balance（以及 list_models 以取得各模型成本）。一個 30 秒的動態圖形影片（使用快速模型）通常約需 33 點數，一分鐘約需 45 點。AI Director 影片成本更高，因為每個場景都是實拍片段。對於任何較長的影片（超過 2 分鐘）或 AI Director，請告訴使用者 list_models 提供的粗略成本，並等待同意。
4. 建立與跟進
- 使用簡報內容呼叫
create_video。它會立即回傳一個任務 ID；建置作業在背景中執行。 - 每 15 到 30 秒輪詢
get_video_status。狀態：queued→processing→rendering→completed，或failed/canceled。一次建置通常需要幾分鐘；速度慢是正常的。千萬不要因為看起來閒置就取消或重新啟動。 awaiting_approval只在你要求storyboard: true時發生：呼叫preview_video， 向使用者展示分鏡板，然後呼叫approve_video傳達他們的決定（或changes）。切勿代他們批准。
5. 交付與迭代
preview_video會顯示每個場景的一幀：將它們展示給使用者。- 修改：使用
edit_video並以平實文字描述修改內容（"讓場景 3 更有衝擊力"、"在結尾使用我們的 Logo"）。只會重新處理該部分。 render_video用於輸出 MP4（預設 720p；1080p 和 4K 需包含在方案中）。然後get_video_status會提供download_url：該網址約在 15 分鐘後過期，因此請將檔案下載到使用者指定的位置（例如./media/），或取得新的連結，而不是儲存舊連結。- 使用者也可以在 Motionvid 應用程式中開啟和編輯影片（狀態中的
app_url）。
規則
- 一次只處理一個影片。在前一個任務仍在執行時，除非被要求，否則不要開始第二個任務。
- 誠實回報完成狀態：如果任務失敗，請如實告知並引用其錯誤訊息；不要宣稱成功。
- 保留使用者對指令、名稱、價格和聲稱的原始措辭。
- 僅在使用者要求時才呼叫
cancel_video。
問題排除
| 症狀 | 處理方式 |
|---|---|
| 工具缺失 / 401 | 重新執行登入步驟（claude mcp login motionvid、codex mcp login motionvid 或重新連接連接器）。 |
| Forbidden / upgrade 訊息 | 該帳戶需要一個付費方案：https://motionvid.ai/pricing |
| 點數不足 | 從 get_credit_balance 告訴使用者餘額；建議縮短影片長度或進行儲值。 |
failed 並顯示 "timed out" | 它已建立的場景會被儲存：使用 edit_video 並帶入 "完成剩餘的場景"。 |
| 429 / 速率限制 | 等待一分鐘，然後重試一次。 |
參考資料
- 代理總覽（Markdown）：https://motionvid.ai/agents.md
- 各用戶端的 MCP 設定：https://motionvid.ai/mcp
- REST API：https://motionvid.ai/api-docs
- 索引：https://motionvid.ai/llms.txt