튜토리얼

이미지 생성 API 속도 제한 상세 해설: 예상되는 상황과 HiAPI가 급증 트래픽을 처리하는 방법

Jun 28, 2026

이미지 API에서 "속도 제한"의 실제 의미

이미지 생성 요청이 HTTP 429로 실패하거나, 배치 작업이 매번 완전히 동일한 동시성 수에서 멈출 때 마주치는 것은 속도 제한이지 버그가 아닙니다. 모든 프로덕션급 이미지 API는 최소 세 가지 차원 중 하나에서 트래픽을 제한하며, 이러한 차이를 이해하는 것이 디버깅에 결정적입니다:

RPM(분당 요청 수)——롤링 60초 창 내에서 발송할 수 있는 POST 호출 수입니다. 급증 트래픽에 관대하고 회복이 빠릅니다.
RPD(일일 요청 수)——일일 상한으로, 보통 요금제 티어에 연동됩니다. UTC 자정(또는 계정의 과금일)에 초기화됩니다.
동시성 / 진행 중 작업 수——동시에 실행할 수 있는 이미지 작업 수입니다. RPM이 정상이더라도 5번째 진행 중 작업은 대기열에 들어가거나 거부됩니다.

이미지 생성에 국한해 보면, 병목은 거의 항상 동시성이지 RPM이 아닙니다. 단일 1024×1024 작업은 종단 간 8–30초가 걸릴 수 있으므로, 10개의 병렬 작업 ≠ 10 RPM입니다. 이 둘을 혼동하는 것이 "내 재시도가 상황을 더 악화시켰다"의 가장 흔한 원인입니다.

적중률 순으로 정렬한 흔한 원인

병렬도가 동시성 상한을 초과했습니다.가장 가능성 높은 원인입니다. 루프가 한 번에 50개의 POST /v1/tasks 호출을 발송하면, 제공자는 앞의 N개를 수락하고 나머지는 429를 반환합니다. 대부분 제공자의 동시성 상한은 키별로 문서화되지 않으며 티어에 따라 추론됩니다.
일시적 오류 이후의 재시도 폭풍.한 작업이 5xx를 반환하면 즉시 재시도가 발동하고, 다른 모든 진행 중 작업도 같은 일을 하여 유효 동시성이 1초 만에 두 배가 됩니다.
알지 못하는 모델별 RPM 상한.높은 티어의 범용 키라도 특히 신규 또는 고급 모델의 경우 모델 차원의 제한을 받을 수 있습니다. 같은 키로 gpt-image-2와 flux-1-pro를 호출한다고 해서 둘이 할당량을 공유하는 것은 아닙니다.
일일 할당량이 정오에 소진됨.덜 흔하지만 가장 혼란스러운 경우입니다. 요청이 정상 작동하다가 매일 같은 벽시계 시각에 실패하기 시작합니다. 항상 RPD입니다.
공유 하위 계정의 노이즈 이웃.키를 환경별로 구성했지만 과금 계정을 공유하면, 스테이징 트래픽이 프로덕션 할당량을 잡아먹습니다.

해결 단계

다음 단계를 순서대로 수행하세요. 각 단계는 서로 다른 차원을 분리합니다.

상태 코드만이 아니라 오류 응답 본문을 읽으세요.HiAPI의 실제 429는 다음과 같습니다:
```
{
  "error": {
    "code": "rate_limit_exceeded",
    "type": "hiapi_error",
    "request_id": "req_01HXXXXXXXXXXXXXXX"
  }
}
```
request_id를 기록하세요. 지원 팀이 어떤 제한에 걸렸는지 정확히 추적할 수 있게 하는 유일한 정보입니다.
429와 401을 구분하세요.{"error":{"code":"permission_denied","type":"hiapi_error","request_id":...}}가 포함된 401은 속도 제한이 아니라 인증 또는 권한 실패입니다. 401에 백오프를 추가하지 마세요. 아무리 기다려도 200이 되지 않습니다.

재시도 횟수보다 먼저 클라이언트 동시성을 제한하세요.간단한 세마포어면 충분합니다:

import asyncio, httpx
sem = asyncio.Semaphore(4)  # 이 값을 제공자의 동시성 상한에 맞추세요

async def submit(client, payload):
    async with sem:
        return await client.post("https://api.hiapi.ai/v1/tasks", json=payload)

4에서 시작하세요. 전체 배치가 429 한 번 없이 실행된 뒤에만 올리세요.

429에서만 완전 지터를 적용한 지수 백오프를 사용하세요.

import asyncio, random
async def backoff(attempt):
    # 1s, 2s, 4s, 8s, 상한 30s, 썬더링 허드 방지를 위해 무작위화
    delay = min(30, 2 ** attempt) * random.random()
    await asyncio.sleep(delay)

재시도 횟수 상한은 5로 설정하세요. 이후에는 실패를 노출하세요. 무한 재시도하지 마세요.

Retry-After가 있으면 따르세요.응답에 Retry-After 헤더가 있으면 제공자가 창이 언제 초기화되는지 명확히 알려주는 것입니다. 그 재시도에는 계산한 백오프 값이 아니라 그것을 사용해야 합니다.
환경별로 키를 분리하세요.스테이징과 프로덕션이 키를 공유하면 동시성 상한도 공유됩니다. 환경당 키 하나 + 고트래픽 작업 풀당 키 하나가 "문서에 적힌 것보다 제한이 더 낮게 느껴진다"를 해결하는 가장 저렴한 방법입니다.

HiAPI가 급증 트래픽을 처리하는 방법

HiAPI는 POST /v1/tasks 엔드포인트를 전면에 두며, 작업을 접수한 뒤 즉시 작업 id를 반환하고, 이후 완료 상태를 폴링합니다. 이 분리는 속도 제한 계산에 중요합니다. 생성 호출은 오버헤드가 낮고 소요 시간이 짧아 RPM 제한이 관대하며, 무거운 작업은 모델 측 동시성으로 제어되는데, 그것이 마땅히 있어야 할 위치입니다. 다운스트림 제공자가 혼잡할 때도 생성 호출은 여전히 성공합니다. 작업은 대기열에서 기다릴 뿐이며, GET /v1/tasks/{id}는 슬롯이 열리기 전까지 status: "queued"를 반환합니다. 다운스트림의 일시적 압력 때문에 429를 보는 일은 결코 없으며, 당신이 자기 키의 할당량을 초과할 때만 보게 됩니다.

이것이 팀의 이미지 워크로드가 단일 계정의 처리 능력을 넘어설 때 제공자 직접 통합에서 HiAPI로 이전하는 실질적 이유입니다. 하나의 Bearer 키, 추론 가능한 속도 제한 예산, 급증 트래픽은 재시도 루프가 아니라 대기열이 흡수합니다.

최소 검증 예제

키가 정상이고 동시성 설정이 합리적인지 확인하는 데 사용하세요. gpt-image-2에 이미지 작업을 제출하고 작업 id를 출력합니다:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": {
      "prompt": "a single red apple on a wooden table, soft daylight",
      "aspect_ratio": "1:1",
      "resolution": "1K"
    }
  }'

예상 응답:

200과 {"id":"task_...","status":"queued"} → 키 정상, 할당량 문제 없음.
429와 {"error":{"code":"rate_limit_exceeded",...}} → RPM, RPD 또는 동시성 제한을 초과했습니다. 위 해결 단계에 따라 속도를 줄이세요.
401과 {"error":{"code":"permission_denied",...}} → 인증 실패이며 속도 제한이 아닙니다. 키를 확인하세요.

빠른 seq 1 10 | xargs -n1 -P10 curl ... 루프로 이 호출을 반복하여 동시성 상한을 찾으세요. 첫 번째로 429를 반환하는 지점이 유효 상한입니다.

자주 묻는 질문

HiAPI에서 gpt-image-2에 공개된 RPM 수치가 있나요? 제한은 티어 기반이며 제공자가 각자의 상한을 조정함에 따라 변경될 수 있습니다. 블로그 글의 숫자를 하드코딩하지 말고 대시보드에서 현재 유효한 제한을 확인하세요.

왜 재시도가 때때로 429를 더 악화시키나요? N개의 병렬 워커에서 순진하게 sleep(1) 재시도를 사용하면 하나의 429가 N개의 동기 재시도로 변해 모두 다시 적중합니다. 고정 지연이 아니라 완전 지터(sleep * random.random())를 사용하세요.

HiAPI는 429 응답에 과금하나요? 아니요. 실패한 작업 생성(429, 401, 일반 4xx)은 과금되지 않습니다. 출력을 성공적으로 생성한 작업에만 지불합니다.

클라이언트에서 동시성을 높이면 상한이 올라가나요? 아니요. 동시성 상한은 서버 측에서 키별로 설정됩니다. 클라이언트 병렬도는 당신이 상한 아래에 머무는지 아니면 상한을 건드리는지를 결정할 뿐입니다.

RPM과 TPM의 차이는 무엇인가요? 이미지 API는 토큰(TPM)이 아니라 요청(RPM) 단위로 제한됩니다. 이미지 작업에는 의미 있는 "토큰" 단위가 없습니다. 대시보드에서 TPM 제한이 보인다면 그것은 /v1/tasks 이미지 작업이 아니라 텍스트/채팅 엔드포인트에 적용됩니다.

고동시성 키 하나를 사용해야 하나요, 아니면 저동시성 키 여러 개를 사용해야 하나요? 이미지 워크로드에서는 논리적 작업 풀당 키 하나가 가장 단순한 사고 모델입니다. 하나의 과금 계정 아래 여러 키는 실제로 할당량을 배가시키지 않으며 할당량을 공유합니다.

더 높은 동시성 상한을 신청할 수 있나요? 가능합니다. 현재 티어에서 지속적인 사용량을 입증하면 됩니다. 지원 팀에 대표적인 429의 request_id를 제공하면 어떤 차원에 걸렸는지 추적할 수 있습니다.

왜 Retry-After 헤더가 보이지 않나요? 모든 제공자가 보내는 것은 아닙니다. 없을 때는 1s부터 시작하는 지터 지수 백오프로 대체하세요. 있을 때는 그 재시도에 대해 그것을 신뢰해야 합니다.