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（可流式 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>发送。 - 出现“禁止”或升级提示意味着账户没有付费计划：告诉用户连接器包含在每一个付费计划中（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 导演：
ai_video: "full"（脚本、一致角色阵容、电影感场景、配音和音乐）。当用户想要先批准角色和故事板时，添加storyboard: true。ai_video: "auto"仅在故事需要的地方混入实拍素材。
可选：enhance_prompt 将粗略想法转化为完整简报。
3. 显示成本后再花费
调用 get_credit_balance（以及 list_models 获取每个模型的成本）。一个 30 秒的动态图形视频在快速模型上通常消耗约 33 积分，一分钟约 45 积分。AI 导演电影成本更高，因为每个场景都是实拍素材。对于任何超过 2 分钟或 AI 导演的内容，从 list_models 告知用户大致成本，并等待同意。
4. 创建并跟进
- 使用简报调用
create_video。它立即返回一个任务 ID；构建在后台运行。 - 每 15 到 30 秒轮询
get_video_status。状态：queued→processing→rendering→completed，或failed/canceled。一次构建通常需要几分钟；慢是正常的。永远不要因为看起来空闲就取消或重新启动。 - 仅当你在
storyboard: true的情况下才会出现awaiting_approval：调用preview_video，向用户展示故事板，然后使用用户的决定（或changes）调用approve_video。永远不要代用户批准。
5. 交付并迭代
preview_video显示每个场景的一帧：展示给用户。- 修改：
edit_video附带纯文字说明的修改内容（“让场景 3 更生动”、“在结尾使用我们的标志”）。仅该部分会重新渲染。 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 或重新连接连接器）。 |
| 禁止 / 升级消息 | 账户需要付费计划：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