MCP 標準生成工作流

先檢查開放狀態

官方 MCP 已在 https://api.animgen.com/mcp 開放公開測試。使用已驗證的 AnimGen 帳戶，通過 OAuth 完成客戶端連線。連線或模型查詢成功不等於批准付費生成。

1. 發現模型

需要預覽後選區、調整 FPS 或複用已有影片時，使用選區與 FPS 分階段流程：quote_video_generation → generate_video → get_video_generation → preview_video → quote_animation_export → export_animation → get_animation_export。兩個付費建立步驟分別確認費用；後續匯出始終複用影片資產 ID。下面保留一鍵幀數工作流。

以空引數物件呼叫 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，然後繼續輪詢。取消屬於盡力而為，不代表一定全額退款。