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 字符。同一账户的有效 API Key 可查询回执；额度耗尽的令牌仍可查询或重放已有回执，过期、撤销、删除的令牌及被禁用的账户不能访问。新生成仍要求有效凭证和足够额度。

原子去重与冲突

路由、计费及联系生成供应商前，数据库先原子保存受理记录。同键同内容返回 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"