중복 방지 - Zet Studio API

POST /generations가 응답 없이 끊기면 작업이 시작됐는지 알 수 없어요. Idempotency-Key를 보내면 안심하고 다시 보낼 수 있어요.

curl -X POST https://api.studio.thezet.io/v1/generations \
  -H "Authorization: Bearer $ZET_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4821-thumbnail" \
  -d '{"model": "z-image-turbo", "prompt": "A red paper boat"}'

어떻게 동작하나요

상황	결과
같은 키, 같은 내용	첫 작업의 현재 상태를 돌려줘요. `202`에 `Idempotent-Replayed: true`가 붙고, 청구되지 않아요.
같은 키, 다른 내용	`409 idempotency_conflict`예요. 새 요청에는 새 키를 써 주세요.
같은 키가 동시에 도착	작업은 하나만 만들어지고 한 번만 청구돼요.
첫 요청이 거절됨 (`400`, `402`, `429`)	작업이 만들어지지 않아서 키를 다시 쓸 수 있어요. 충전한 뒤 같은 키로 보내도 돼요.
첫 작업을 삭제한 뒤 다시 보냄	삭제된 작업을 돌려주고 다시 청구하지 않아요.

키 만들기

사용자의 행동 하나당 키를 하나 만들고, 호출하기 전에 자기 DB에 저장해 주세요. 재시도할 때 같은 키를 읽어서 보내면 돼요.
공백 없는 ASCII 문자 255자까지 쓸 수 있어요. UUID나 order-4821-thumbnail 같은 값이 좋아요.
키는 계정 단위예요. API 키를 바꿔도 그대로 동작하고, 다른 고객사와는 겹치지 않아요.
키에는 유효기간이 없어요. 재사용하지 마세요.

JSON 필드 순서가 달라도 내용이 같으면 같은 요청으로 봐요.

키를 보내지 않으면 보낼 때마다 새 작업이 만들어지고 청구돼요. 운영에서는 항상 보내는 걸 권장해요.