API 문서 · 작업

멱등성

Idempotency-Key의 의미와 재시도 방법.

작업 생성에는 Idempotency-Key 헤더가 필수이며 최대 128자입니다(없거나 너무 길면 400 invalid_request 반환). 주문 번호와 버전을 조합하는 등 서비스 측의 고유 ID를 사용하는 것을 권장합니다.

같은 키, 같은 요청 본문: 202와 처음 생성된 작업(현재 상태)을 Idempotent-Replayed: true 응답 헤더와 함께 반환하며, 예치나 차감이 중복되지 않습니다.
같은 키, 다른 요청 본문: 409 idempotency_conflict를 반환합니다.
멱등 키는 30일간 보관되며 계정 단위로 분리됩니다. 같은 계정의 서로 다른 Key는 하나의 멱등 공간을 공유합니다.

네트워크 타임아웃, 5xx 또는 internal_error가 발생하면 같은 키로 재시도하면 됩니다. 새로 생성하려면(예: 프롬프트 변경) 새 키를 사용하세요.

Node.js

// 서비스 측 고유 ID를 멱등 키로 사용: 타임아웃 후 재시도해도 작업이 중복 생성되지 않음
async function submit(order) {
  const key = `order-${order.id}-v${order.revision}`;
  for (let attempt = 0; attempt < 5; attempt++) {
    try {
      const res = await fetch("https://cn-api.aitoken.tools/v1/videos/generations", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.AITOKEN_API_KEY}`,
          "Idempotency-Key": key,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(order.payload),
      });
      if (res.status < 500 && res.status !== 429) return res.json();
    } catch {
      // 네트워크 오류: 같은 key로 계속 재시도
    }
    await new Promise((r) => setTimeout(r, 2 ** attempt * 1000 + Math.random() * 500));
  }
  throw new Error("submit failed");
}