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 指回執取回；僅 not_accepted 會有 new_submission_safe=true。未知結果或 accepted 且 task_ready=false 時，向支援提供回執/請求 ID、模型和 UTC 時間，勿傳 API Key。不保證官方上游冪等；直接傳此標頭給官方不會取得網關保證。舊真人素材回執沿用原重播流程，查詢可能回傳舊結構。

呼叫範例

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"