2026-09-25개발자

AI 영상 API 멱등성 키: 이중 과금 없이 재시도하기

멱등성 키를 쓰면 재시도한 생성 요청이 두 번째 유료 작업 대신 원래 실행이나 Job을 돌려줍니다. Sume의 Idempotency-Key가 API별로 어떻게 동작하는지 설명합니다.

읽는 시간 5분Sume

멱등성 키는 유료 생성 요청과 함께 보내는 문자열로, 재시도했을 때 두 번째 실행이나 Job을 시작해 과금하는 대신 원래 실행이나 Job을 돌려받게 해 줍니다. Sume에서는 모든 생성 요청에 Idempotency-Key 헤더를 보내고, 그 값은 요청한 시점이 아니라 주문 ID와 버전처럼 만들고 있는 대상에서 유도하세요.

아래 규칙은 2026-09-25에 확인한 Sume 문서 Format 호출하기 (영문), Job과 결과 (영문), Video Generation (영문), Agent Completions, MCP 도구와 게이트 페이지에서 가져왔습니다.

AI 영상 API에는 왜 멱등성 키가 필요한가요?

영상 작업은 그 작업을 요청한 호출보다 오래 이어집니다. sync 제출도 최대 30초까지만 기다리는데, 영상 Job은 대개 그보다 오래 걸립니다. 2xx는 Job이 끝났다는 뜻이 아니라 Job이 존재하고 유료 작업이 진행 중이라는 뜻입니다. 또 클라이언트 쪽 타임아웃은 Job을 취소하지 않으므로, Job은 계속 실행되고 계속 과금됩니다.

그러니 로컬 프로세스가 타임아웃됐다는 이유만으로 유료 요청을 다시 제출하지 마세요. 제출을 꼭 재시도해야 한다면 같은 Idempotency-Key를 재사용하세요. 그러면 재시도가 두 번째 Job을 과금하는 대신 원래 Job을 돌려줍니다.

멱등성 키는 어떻게 만들어야 하나요?

안정적인 식별자, 즉 주문 ID와 의도적으로 다시 실행하고 싶을 때 올리는 버전에서 유도하세요.
요청마다 절대 새로 생성하지 마세요. 요청마다 uuidgen을 쓰면 헤더는 장식에 불과합니다.
키는 같은 작업, 같은 페이로드에만 재사용하세요.
Format 실행에서 키는 최대 255자이며, 본문 필드 idempotency_key도 쓸 수 있습니다. 둘 다 보내면 헤더가 우선합니다.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-promo/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8823-promo-v1" \
  -d '{ "input": { "product_url": "https://shop.example.com/p/8823" } }'

같은 키로 다시 보내면 어떻게 되나요?

Format 실행에서 새 생성 요청은 202로, 재전송은 원래 영수증과 함께 200으로 응답하므로, 코드에서는 둘 다 성공으로 처리하고 data.id를 저장하면 됩니다. 멱등성 (영문) 항목에 나온 결과 전체는 다음과 같습니다.

Format 실행 재전송, Format 호출하기 (영문) 기준, 2026-09-25 확인.
재전송	결과
같은 키, 같은 본문	원래 영수증과 `idempotency_hit: true`가 담긴 `200`. 두 번째 실행도, 두 번째 청구도 없음
같은 키, 다른 본문(다른 `instruction`이나 첨부 목록 포함)	`409 idempotency_conflict`. 아무것도 실행되지 않음
같은 키로 같은 순간에 보낸 요청 두 개	하나가 이기고, 다른 하나는 재시도할 수 있는 `409 idempotency_key_in_use`를 받음. 1초쯤 기다렸다가 다시 보내기
실패한 생성 요청(`402`, `503`, …) 뒤의 같은 키	키가 해제됨. 원인을 고친 뒤 같은 키로 재시도

Sume의 어떤 엔드포인트가 멱등성 키를 받나요?

아래의 모든 생성 표면이 멱등성 키를 받습니다. POST /v1/videos에서 이 키는 OpenRouter Video Generation API와의 문서화된 차이점 (영문) 가운데 하나로, OpenRouter의 해당 경로에는 멱등성 키가 없습니다. model: "sume/auto"를 쓰면 재전송도 가격과 라우팅이 똑같습니다. 자세한 내용은 OpenRouter 호환 영상 생성에 있습니다.

Format 호출하기 (영문), Agent Completions, Job과 결과 (영문), Video Generation (영문), MCP 도구와 게이트 기준, 2026-09-25 확인.
표면	보내는 방법	재전송 시
Format 실행	모든 생성 요청에 `Idempotency-Key` 헤더	`200`, 원래 영수증, `idempotency_hit: true`
Agent Completions	`Idempotency-Key` 헤더	`idempotency_hit: true`가 담긴 원래 영수증
생성 Job 제출	`Idempotency-Key` 헤더	두 번째 청구 대신 원래 Job
`POST /v1/videos`	`Idempotency-Key` 헤더	원래 Job
호스팅 MCP 쓰기·유료 도구	`idempotency_key` 인자, 필수	전송과 중복 제거용이며 사람의 승인이 아님

curl -sS -X POST "https://api.sume.com/v1/videos" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: desk-clip-8823-v1" \
  -d '{
    "model": "sume/auto",
    "prompt": "A vertical UGC-style product clip on a desk, natural light",
    "aspect_ratio": "9:16",
    "duration": 5
  }'

타임아웃 뒤에는 다시 제출하는 대신 무엇을 해야 하나요?

기존 Job을 다시 이어 가세요. 아래 단계는 Job과 결과 (영문)에서 가져왔습니다.

이미 가진 Job을 GET /v1/jobs/{id}/status에서 지수 백오프로 폴링하고, next_poll_after_seconds가 있으면 그 값을 따르세요. /v1/videos에서 만든 Job도 여기서 보입니다.
대기 예산을 다 쓴 sync 제출도 Job ID와 함께 2xx를 반환합니다. status_url로 이어 가세요.
호스팅 MCP 서버에서 jobs_wait는 호출당 최대 55초 동안 기다립니다. wait_slice_expired나 524 전송 실패가 나면 같은 ID로 jobs_wait를 다시 호출하고, 유료 생성 요청은 절대 다시 제출하지 마세요.
클라이언트 쪽 타임아웃은 아무것도 취소하지 않습니다. 취소는 POST /v1/jobs/{id}/cancel로 하며, 생성 작업이 시작되기 전에만 됩니다.

멱등성 키가 하지 않는 일은 무엇인가요?

지출을 승인하지 않습니다. 호스팅 MCP 도구에서 미리 보려면 dry_run=true를, 상한을 두려면 max_spend_usd를 쓰세요. max_spend_usd는 보냈을 때만 강제됩니다. 무인 AI 에이전트 지출 상한을 참고하세요.
바뀐 요청은 다루지 않습니다. 같은 키에 다른 본문을 보내면 새 실행이 아니라 409입니다.
여러 Format에 걸쳐 적용되지 않습니다. 같은 키를 두 Format에 보내면 실행이 두 개 시작됩니다.

출처

작성자 Sume