タスクを確認し、利用可能な成果物を保存する

作成応答は完成ではない

POST /animationsはHTTP 202でタスクIDとRetry-Afterを返します。まずIDを保存します。キューへの受理は完成を意味しません。GET /animations/{id}を繰り返し、サーバーのRetry-After（現在は通常約5秒）を優先します。一時エラーには上限付きのバックオフと全体の期限を設けます。遅いだけで別タスクを作らないでください。現在の公開フローはWebhookではなくポーリングです。

状態と段階

stageは必要に応じてvideo_generationやanimation_exportを示します。progressは0～1の進度であり残り時間の保証ではありません。ポーリング間に中間状態を飛ばす場合があります。credits.quoted、credits.held、credits.chargedは別の会計状態で、足し合わせたり最初の見積もりを最終請求とみなしたりしないでください。

部分的な成果物も確認する

ワンクリック処理で元動画が完成してから書き出しに失敗することがあります。succeeded以外の終状態でも必ずoutputsを読みます。利用可能なファイルを保存し、エラーと欠けた形式を記録して部分成功と報告します。必要な処理だけを再試行してください。既存の元動画は/animation-exportsで再利用でき、動きを再生成する必要はありません。

安全にダウンロードする

素材にはid、format、mime_type、byte_size、download_url、download_expires_atがあります。

1. 長期的な状態管理にはタスクIDか素材IDを保存します。
2. 返された署名付きURLから実バイトを取得します。
3. 署名付きURLや転送先ストレージにAPI Bearerヘッダーを付けません。
4. 自分で決めたファイル名で保存し、完了を確認します。
5. 期限切れならAPIキー付きの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は別で、取り違えないでください。単純なワンクリックの流れはクイックスタートを参照してください。