MCP 标准生成工作流

先检查开放状态

官方 MCP 已在 https://api.animgen.com/mcp 开放公开测试。使用已验证的 AnimGen 账户，通过 OAuth 完成客户端连接。连接或模型查询成功不等于批准付费生成。

1. 发现模型

以空参数对象调用 list_models，选择实际返回的模型 ID 与合法配置。不要假设所有模型都支持尾帧、参考图、负向提示词、seed，或相同的时长与比例。

2. 传输本地图片

本地路径不是 ImageInput，上传桥接包含三个独立步骤：

1. 用 filename、mime_type 和准确的 byte_size 调用 prepare_image_upload。
2. 在 expires_at 之前，使用返回的 HTTP method、upload_url 和 headers 发送实际文件字节。这一步由获准的客户端能力执行，不是把路径交给 MCP 就能完成。
3. 用 upload_id 调用 complete_image_upload，取得用于生成请求的 file_id。

不要把 MCP Token 或 API Key 附加到上传目标，只使用本次上传返回的请求头。上传 URL 属于敏感信息。客户端无法传输字节时，应使用获准且支持上传的客户端能力、合规公开 HTTPS 图片或大小限制内的 Base64，不能假装上传成功。

3. 构造请求并报价

下面是 quote_animation 的参数结构。UUID 为占位符，应换成已完成上传返回的 file_id。实际请求还应设置选定模型及其合法参数。

{
  "request": {
    "input": {
      "first_frame": {
        "type": "file",
        "file_id": "00000000-0000-4000-8000-000000000001"
      }
    },
    "prompt": "A character runs in place, side view, fixed camera.",
    "selection": {"mode": "full"},
    "export": {
      "output_formats": ["frames_zip"],
      "frame_count": 24,
      "output_width": 512,
      "output_height": 512
    }
  }
}

结果包含 quote_id、credits、breakdown 与 expires_at。报价不会启动生成。向用户说明目标产物和费用，获得批准后再继续。

4. 批准后才生成

调用 generate_animation，传入同一个 request、已持久化的 idempotency_key，以及经批准的 quote_id 和／或 max_credits。这三个字段与 request 同级，不是写进 request 内部。

适合时可同时提供新鲜报价和支出上限。上限必须来自用户批准，不能由 AI 自行编造。实现重试前先读支出保护。

保存返回的任务 ID。工具返回异步任务，不代表下载已经完成。

5. 轮询到终态

用 animation_id 调用 get_animation。采用有界轮询间隔（可从约五秒开始），并设置截止时间。工具返回结构化 JSON，不要假设 MCP 传输会暴露 API 的 HTTP Retry-After 响应头。

处于 queued、running 或 cancelling 时继续轮询；进入 succeeded、failed 或 cancelled 后停止。失败也要检查 outputs，导出失败时可能已有源视频。

6. 下载真实文件

对每个可用资产，用 asset_id 调用 download_asset。返回的是资产信息和签名下载 URL，不会自动保存本地文件。

使用获准的客户端下载能力，不要转发 OAuth 或 API 凭据。私密保存文件，再报告本地位置或合适的用户附件，不直接输出原始签名 URL。链接过期时，通过 download_asset 重新获取信息。

需要取消时，用 animation_id 调用 cancel_animation，然后继续轮询。取消属于尽力而为，不代表一定全额退款。