Seedance の冪等送信と障害復旧

seedance-2.0、seedance-2.0-fast、seedance-2.0-mini、seedance-2.5 の生成要求に Idempotency-Key を付けます。対象は POST /v1/videos、POST /v1/videos/generations、POST /v1/video/generations で、キーの名前空間は共通です。画像生成、見積もり、remix と他の動画モデルは対象外です。キーなしの要求には汎用的な重複防止保証がありません。

範囲とキー

キーは APIMaster アカウント内の Seedance 動画生成操作に属し、API Key やモデルごとではありません。新しい生成ごとに 8–128 文字の可視 ASCII からなるランダムな新規キーを使います。同じアカウントの有効な認証キーで検索できます。残高を使い切ったトークンでも既存記録の検索・再取得は可能ですが、失効・無効化・削除済みキーや停止アカウントは不可です。新規生成には有効な認証と十分な割り当てが必要です。

原子的な再取得と競合

経路選択、課金、生成サービスへの接続前にデータベースへ原子的に記録します。同じキーと内容は HTTP 202 で元の記録と事前割当タスク ID を返し、同時再試行や再起動でも再送信・再引き当てしません。内容変更は HTTP 409（idempotency_conflict）です。JSON のオブジェクト順と空白は無視しますが、配列順、数値、省略と明示した既定値、モデル、通知、経路グループ・指定チャネルは区別します。multipart の境界とファイル名は無視し、ファイル内容と順序を比較します。元の本文と経路を維持し、JSON と multipart を混用しないでください。記録は最低 30 日保持し、本版は自動削除やキー再利用を行いません。

応答

初回は通常の作成応答です。X-Video-Submission-Id、要求 ID、タスク ID を保存します。再取得は受付記録であり初回と同じ応答形式とは限りません。事前割当 ID は上流の受付を証明しません。accepted は生成完了ではありません。task_ready=true の場合だけ元のタスクを検索し、それ以外は再送せずサポートへ連絡します。

送信状態

pending：ゲートウェイに記録済み、未送信。submitting：送信開始、結果待ち。accepted：上流タスク ID を受領。not_accepted：上流へ未送信、修正後に新規キーで作成可能。acceptance_unknown：受付の可能性があるが確認なし、再生成禁止。障害で残った記録は 30 分後の検索で送信前なら not_accepted、送信後なら acceptance_unknown になります。自動再送はしません。送信状態と課金状態は異なり、既存の引き当て・精算・返金照合は継続します。

復旧手順

タイムアウトや 5xx 後はタスク ID がなくても元のキーで検索します。同一キー・同一内容の再取得は安全ですが失敗した送信を再開しません。404、空の一覧、課金ログなしでは未受付を証明できません。元の要求が通信中、キーなし、機能導入前の場合があります。same_key_replay_safe は記録再取得を意味し、new_submission_safe=true は not_accepted のみです。不明または accepted かつ task_ready=false なら記録/要求 ID、モデル、UTC 時刻をサポートへ伝え、API Key は送らないでください。上流の冪等性は保証せず、公式 API への同ヘッダー送信にもこの保証はありません。旧人物素材記録は従来の再取得手順と旧形式を維持します。

使用例

curl --fail-with-body 'https://apimaster.ai/v1/videos' \
  -H "Authorization: Bearer $APIMASTER_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: seedance-order-20261014-001' \
  -d '{"model":"seedance-2.0","prompt":"A paper boat on a pond","duration":4,"resolution":"480p","generate_audio":false}'

curl --fail-with-body 'https://apimaster.ai/v1/video-submissions/by-key' \
  -H "Authorization: Bearer $APIMASTER_KEY" \
  -H 'Idempotency-Key: seedance-order-20261014-001'

{
  "code": 200,
  "data": {
    "submission_id": "HASH",
    "task_id": "task_PUBLIC_ID",
    "request_id": "ORIGINAL_REQUEST_ID",
    "model": "seedance-2.0",
    "status": "accepted",
    "task_ready": true,
    "created_at": 1791936000,
    "updated_at": 1791936001,
    "next_action": "query_task",
    "same_key_replay_safe": true,
    "new_submission_safe": false,
    "retention": "at_least_30_days_no_automatic_key_reuse"
  }
}

curl --fail-with-body 'https://apimaster.ai/v1/videos/task_PUBLIC_ID' \
  -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/videos/task_PUBLIC_ID/billing' \
  -H "Authorization: Bearer $APIMASTER_KEY"