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 및 다른 영상 모델은 제외됩니다. 키 없는 요청에는 일반 제출 중복 방지 보장이 없습니다.

범위와 키

키 범위는 개별 API Key나 모델이 아닌 APIMaster 계정의 Seedance 영상 생성 작업입니다. 새 생성마다 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는 보내지 마세요. 공식 공급자의 멱등성은 보장하지 않으며 직접 같은 헤더를 보내도 게이트웨이 보장은 적용되지 않습니다. 기존 인물 소재 기록은 원래 재생 경로와 기존 응답 형식을 유지합니다.

호출 예제

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"