API 快速開始：從圖片到下載資產

前提條件

開放 API 處於公開測試階段。你需要已驗證的 AnimGen 帳戶、包含 animations:read 和 animations:write 的 API Key，以及可信服務端或本地機器。生成要求帳戶點數充足；訂閱會提高開發者限額，但不是訪問前提。

在帳戶 → 開發者建立 Key。通過金鑰管理器或私有 Shell 會話提供 ANIMGEN_API_KEY 環境變數。不要寫進瀏覽器 JavaScript、釋出的遊戲、程式碼倉庫或 AI 對話。

基礎地址為 https://api.animgen.com/v1。URL 的相容性版本是 v1，本文對應的契約版本是 1.4.0。

1. 發現可用模型

curl --fail-with-body https://api.animgen.com/v1/models \
  -H "Authorization: Bearer $ANIMGEN_API_KEY"

從 data 中選擇支援目標輸入模式的 id，檢查時長、解析度、比例和能力標誌。不要直接使用舊文章中的模型名。

下面的首幀示例要求模型的 supports_first_frame 為 true，且 modes 支援首幀。示例使用該模型當前公佈的預設選項。

2. 準備請求並報價，不啟動生成

下載並檢查 Python 完整工作流示例。它要求 Python 3.10+，僅使用標準庫。

curl --fail-with-body -o animation-workflow.py \
  https://animgen.com/examples/animation-workflow.py

python3 animation-workflow.py prepare \
  --image character.png \
  --model 'PROVIDER:MODEL_FROM_CATALOG' \
  --prompt '同一角色原地跑步，側面視角，鏡頭固定。' \
  --state hero-run.json

替換圖片路徑和模型 ID。準備階段會檢查模型目錄，生成 Base64 請求，獲取報價與餘額，並寫入私有狀態檔案；不會呼叫付費建立介面。

狀態檔案包含原圖和提示詞，請勿提交到版本控制，限制訪問，並在不再需要時刪除。檔案不包含 API Key。

3. 明確批准建立

核對點數報價，將 APPROVED_CREDITS 設定為你接受的金額，再執行：

python3 animation-workflow.py run \
  --state hero-run.json \
  --approve-credits "$APPROVED_CREDITS" \
  --output ./hero-output

首次建立前，指令碼會重新報價；超過本地批准金額時停止。它會儲存冪等鍵，以同一請求執行一次邏輯建立，然後輪詢並下載產物。

4. 安全恢復並檢查結果

命令超時後，使用同一個狀態檔案重新執行。如果檔案已有任務 ID，指令碼只恢復輪詢，不會再建立。建立響應不明確時，會在保守重試視窗內複用原始冪等鍵與請求內容。

不要刪除狀態檔案、重新準備來“重試”，那會變成新邏輯操作，可能重複付費。示例對超過 24 小時仍無法確認結果的建立拒絕自動重試；請先檢查任務列表或聯絡支援。

進入任何終態後，指令碼都會先儲存可用資產，再報告失敗或取消。結果不完整時返回非零退出碼，不把部分產物當作全部成功。檔名使用資產 ID，不使用遠端提供的任意名稱。

請求會做什麼

示例使用普通模式、完整影片區間，並請求 PNG 幀 ZIP、24 幀、512 × 512 尺寸。這些只是示例選擇，不是 API 預設值，也不是適合所有專案的質量建議。

複用上傳檔案或使用公開圖片 URL，見鑑權與圖片輸入。任務生命週期見輪詢與下載、錯誤與重試。精確契約可下載 OpenAPI JSON。

Python 示例通過本地 Mock 測試驗證，沒有通過真實付費生成來做測試。正式接入時，使用一個小型且明確批准費用的任務自行驗收。其他語言與各自驗收範圍見完整呼叫示例，準確引數見自動生成的 API 參考。