Seedance idempotency and submission recovery

For seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, and seedance-2.5, add Idempotency-Key to generation requests. Supported paths are POST /v1/videos, POST /v1/videos/generations, and POST /v1/video/generations; they share one key namespace. Image generation, quotes, remix endpoints and other video models are not covered. Requests without a key retain existing behavior and have no general submission deduplication guarantee.

Scope and keys

Keys are scoped to the APIMaster account and Seedance video-generation operation, not to one API key or model. Use a unique random key of 8–128 visible ASCII characters for each new generation. A valid key from the same account can query the receipt. Exhausted tokens may query or replay existing receipts; expired, revoked or deleted keys and blocked accounts cannot. New generation still requires valid credentials and sufficient quota.

Atomic replay and conflicts

An atomic database claim is saved before routing, billing or contacting the generation provider. Same key and payload return HTTP 202 with the original receipt and preallocated task ID, without executing another submission or precharge, including concurrent requests and server restarts. A changed request returns HTTP 409 (idempotency_conflict). JSON object order and whitespace are ignored; array order, numbers, omitted versus explicit defaults, model, notification settings and routing group/channel are significant. Multipart boundaries and filenames are ignored, but upload bytes and their order are significant. Keep the original body and routing settings unchanged; JSON and multipart are distinct. Receipt records are retained for at least 30 days; this release has no automatic deletion or key reuse. Always use a new key for a new generation.

Responses

First requests retain the normal creation response. Save X-Video-Submission-Id, the request ID and task ID. Replays return a receipt, not necessarily the original response envelope. A preallocated task ID alone is not proof of upstream acceptance. accepted means provider acceptance, not completed generation. Only poll the task when task_ready=true; otherwise contact support without resubmitting.

Submission states

pending: recorded at the gateway, provider submission has not begun. submitting: provider submission has begun and the outcome is pending. accepted: a provider task ID was received. not_accepted: no provider submission occurred; correct the error before creating a new request with a new key. acceptance_unknown: the provider may have accepted the request, but confirmation is missing; do not create another generation. A receipt left unfinished by a crash is classified on lookup after 30 minutes: pre-send becomes not_accepted, post-send becomes acceptance_unknown. No state automatically resubmits. These states describe submission, not billing; existing reservations, settlement and refund reconciliation still apply.

Recovery

After a timeout or 5xx, query by the same key, even if no task ID was received. Replaying the identical keyed request is safe within this scope, but it does not restart a failed submission. Lookup 404, an empty task list or absent billing logs do not prove non-acceptance: an original request can still be in flight, or may have been submitted without a key or before this feature. same_key_replay_safe refers to duplicate receipt retrieval; new_submission_safe is true only for a confirmed not_accepted receipt. For unknown outcomes or accepted with task_ready=false, contact support with the receipt/request ID, model and UTC time; never send your API key. Upstream idempotency is not promised, and sending the header directly to the official provider does not provide this gateway contract. Older portrait receipts remain on their original replay path and may return their legacy schema through lookup.

Examples

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"