輪詢任務並下載可用產物

建立響應不等於動畫完成

POST /animations 返回 HTTP 202、任務 ID 和 Retry-After。收到 ID 後優先儲存；進入佇列不代表生產已經完成。

輪詢 GET /animations/{id}。優先遵循服務的 Retry-After（目前通常約五秒），遇到臨時錯誤使用有界退避，並設定總體截止時間。不要因為輪詢慢就建立新任務。當前公開流程以輪詢為主，不提供 Webhook 工作流。

狀態與階段

stage 在適用時標明 video_generation 或 animation_export。progress 範圍為 0 到 1，不是精確剩餘時間。兩次輪詢間任務可能跨過多個狀態，不保證你觀察到每個中間狀態。

credits.quoted、credits.held、credits.charged 分別表示報價、預佔和已扣，不要把初始報價當作最終扣費，也不要把三者相加。

失敗仍可能有可用產物

一鍵任務可能先成功生成源影片，再在匯出階段失敗。進入終態時，無論 status 是否為 succeeded，都要檢查 outputs。

先下載已有資產，再記錄錯誤和缺失的請求格式，準確報告部分完成。只重做必要步驟：已有源影片可以通過 /animation-exports 重新匯出，不必重新生成動作。

安全下載

每個資產包含 id、format、mime_type、byte_size、download_url 和 download_expires_at。

1. 用任務 ID 或資產 ID 儲存長期應用狀態。
2. 使用返回的簽名 URL 下載位元組。
3. 不要把 API Bearer 頭髮送給簽名 URL 或重定向後的儲存主機。
4. 使用應用自己決定的檔名，並確認下載完整。
5. 連結過期時，用 API Key 呼叫 GET /assets/{asset_id} 獲取新連結。

連結有效期較短，應讀取 download_expires_at，不要寫死時長。資產已受儲存或保留策略移除時，重新查詢不會恢復檔案。

簽名 URL 相當於臨時憑據，不應釋出到日誌、分析事件、工單或 AI 對話記錄。

取消任務

對歸屬自己的任務呼叫 POST /animations/{id}/cancel。取消屬於盡力而為，返回的可能仍是中間狀態；繼續輪詢到終態。任務完成也可能先於取消生效。

已經執行的生產可能保留扣費，未消耗的預佔可以釋放。應檢查返回的點數資料，不要承諾一定全額退款。

先稽核再匯出：兩階段流程

使用 POST /video-generations 建立影片，再輪詢 GET /video-generations/{id} 取得影片資產。稽核後，把 source_video_asset_id、選段和匯出設定提交到 POST /animation-exports，輪詢 GET /animation-exports/{id}。

每個新的付費建立操作都應先報價，並使用自己的冪等鍵。源資產 ID 和任務 ID 不是同一種資源，不能互換。快速開始示例演示的是更簡單的一鍵生命週期。