요청 제한

모든 사용자의 지연 시간을 예측 가능하게 유지하기 위해 두 가지 한도가 있습니다. 인증된 요청에는 요청 속도 한도, 동시에 실행되는 생성에는 동시 실행 한도가 적용됩니다. 요청 속도를 넘으면 429 rate_limited가 반환되며 요금은 청구되지 않습니다. 동시 실행 한도를 넘어도 거부되지 않습니다. 생성은 계정 대기열에서 기다리다가 진행 중인 생성 하나가 끝나는 즉시 시작됩니다.

기본 제한#

요청 한도는 토큰 버킷 방식입니다. 한 번에 최대 20개 요청을 보낼 수 있고 초당 10씩 용량이 회복됩니다. 초당 10회 이하의 일정한 요청은 제한되지 않습니다.

대기열#

• 동시 실행 한도를 넘은 생성도 평소처럼 접수됩니다. id를 바로 받고, 가격은 보류되며, 상태는 queued입니다. 진행 중인 생성 하나가 끝나는 즉시 가장 오래된 것부터 자동으로 시작됩니다.
• 대기 시간은 생성의 시간 제한에 포함되지 않습니다. 대기열에서 기다린다는 이유로 실패하거나 시간 초과되지 않습니다.
• 대기열에서 기다리는 생성은 언제든 취소(POST /generations/{id}/cancel)하거나 삭제할 수 있으며, 보류된 금액은 즉시 환불됩니다. 시작된 뒤에는 일반 취소 규칙이 적용됩니다.
• 대기열에는 동시 실행 한도의 최대 10배까지 들어갑니다(새 계정은 200개). 그 이상이면 요청에 429 rate_limited가 반환되며, 아무것도 생성되거나 청구되지 않습니다.
• 대기열은 계정마다 따로 있으며, 기다리는 생성은 용량을 차지하지 않습니다. 대기열이 길어도 다른 계정의 생성이 늦어지지 않습니다.

내 한도 확인#

표는 기본값입니다. 계정 자체의 한도와 진행 중인 생성 수는 대시보드 → 설정와(과) GET /api/v1/account(및 MCP 도구 get_account)의 limits 필드에서 확인할 수 있습니다:

{
  "object": "account",
  "balance_usd": 42.5,
  "limits": {
    "unlimited": false,
    "concurrent_generations": 20,
    "in_flight": 3,
    "requests_per_second": 10,
    "burst": 20,
    "tier": null
  }
}

concurrent_generations은(는) 동시에 실행할 수 있는 생성 수(넘는 생성은 대기열에서 기다림), in_flight은(는) 지금 진행 중인 수(대기 중인 생성 포함)입니다. requests_per_second와(과) burst은(는) 요청 속도와 버스트로, 계정과 각 API 키에 적용됩니다.

제한에 도달한 경우#

{
  "error": {
    "code": "rate_limited",
    "message": "Your queue is full: 200 generations are already waiting for your 20 concurrent slots (up to 200 can wait). Nothing was submitted or charged. Retry when some have finished (webhook_url tells you when), or cancel queued ones; GET /api/v1/account shows your limits. For a higher limit, contact us: contact@cheapergen.com."
  }
}

모든 429 응답에는 Retry-After 헤더(대기할 초)가 포함됩니다. 한도에 도달한 경우 메시지에 그 한도가 표시되고, 대기열이 가득 찬 경우 기다리는 생성 수도 표시됩니다.

• 요청 속도 제한: 잠시 기다린 뒤 지수 백오프와 지터를 적용해 재시도하세요(약 1초부터 시작). 자세한 내용은 안전하게 재시도하기에서 확인하세요.
• 대기열 가득 참: 동시 실행으로 인한 429는 대기열이 가득 찼을 때만 반환됩니다. 생성이 끝날 때까지 기다리거나(webhook_url로 알림을 받을 수 있습니다) 대기 중인 생성을 취소한 뒤 다시 제출하세요.

제한 내에서 사용하기#

짧은 간격으로 폴링하는 대신 웹훅 사용하기#

작업을 수십 개 실행하며 매초 폴링하면 요청 한도를 빠르게 소진합니다. 제출할 때 webhook_url을 전달해 서버가 완료 시 호출하도록 하세요. 자세한 내용: 웹훅. 직접 폴링한다면 동영상은 5–10초 간격으로 늘리세요.

요청을 자체 대기열에 넣기#

짧은 순간 몰리는 요청은 괜찮습니다. 대기열이 받아 줍니다. 대기열보다 큰 배치는 남은 작업을 직접 보관하고 생성이 끝날 때마다 제출하세요(웹훅으로 알림을 받을 수 있습니다). 그러면 대기열이 가득 찼다는 429를 받지 않습니다.

서비스별로 키 하나 사용하기#

요청 속도는 키별로 계산하지만 동시 실행 수는 계정별로 계산합니다. 키를 여러 개로 나눠도 한 번에 실행할 수 있는 생성 수는 늘어나지 않습니다.