GPT Image Hub API 문서

모델 목록을 제외한 모든 v1 엔드포인트에는 Authorization 헤더에 API 키가 필요합니다. 원시 키는 생성 시 한 번 표시됩니다. 서버는 해시만 저장합니다.

Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

모델 엔드포인트는 모델 ID, 공급자, 지원되는 종횡비, 지원되는 품질, 참조 이미지 제한 및 이미지당 크레딧을 반환합니다.

curl https://www.gptimagehub.com/api/v1/models

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image-turbo",
    "prompt": "A cinematic product photo with premium studio lighting",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
  }'

크레딧 엔드포인트는 API 키를 소유한 사용자에 대한 잔액, 계정 유형 및 향후 크레딧 만료를 반환합니다.

curl https://www.gptimagehub.com/api/v1/credits \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

이미지 생성 엔드포인트는 기본적으로 생성이 완료될 때까지 기다립니다. async를 true로 설정하면 generation id를 즉시 받을 수 있으며, /api/v1/generations/:generationId를 폴링해 결과를 확인합니다. 크레딧은 공급자 생성 전에 차감되며, 공급자 쪽에서 실패하거나 요청보다 적은 이미지를 반환하면 자동으로 환불됩니다.

JSON 요청

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic product photo of a transparent perfume bottle on black marble",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
  }'

비동기 작업

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-hero-image" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic product photo with premium studio lighting",
    "size": "1024x1024",
    "quality": "high",
    "n": 1,
    "async": true
  }'

{
  "object": "image_generation",
  "id": "clx_generation_log_id",
  "status": "queued",
  "model": "gpt-image-2",
  "aspect_ratio": "1:1",
  "quality": "1K",
  "created_at": "2026-04-30T08:00:00.000Z",
  "images": [],
  "usage": {
    "credits": 0,
    "credits_requested": 7
  },
  "poll_url": "https://www.gptimagehub.com/api/v1/generations/clx_generation_log_id"
}

참조 이미지 요청

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "model=gpt-image-2" \
  -F "prompt=Use the reference image and render it as a premium studio product shot" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "n=1" \
  -F "reference_image=@./reference.png"

응답

{
  "object": "image_generation",
  "id": "clx_generation_log_id",
  "status": "succeeded",
  "model": "gpt-image-2",
  "aspect_ratio": "1:1",
  "quality": "1K",
  "images": [
    {
      "id": "clx_image_id",
      "object": "image",
      "url": "https://cdn.example.com/generations/user/image.png",
      "created_at": "2026-04-30T08:00:00.000Z"
    }
  ],
  "usage": {
    "credits": 7
  },
  "balance": {
    "credits": 113,
    "account_type": "PRO",
    "next_expiration": null
  }
}

생성 엔드포인트가 반환한 ID로 저장된 생성 로그와 이미지 URL을 조회합니다. API 키로는 같은 사용자가 소유한 생성 기록만 읽을 수 있습니다.

curl https://www.gptimagehub.com/api/v1/generations/clx_generation_log_id \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "error": {
    "message": "Invalid request body",
    "code": "invalidRequest"
  }
}

• 프로덕션 환경에서 동기식 생성은 최대 800초 동안 실행될 수 있습니다.
• n은 1에서 4 사이여야 합니다.
• 참조 이미지는 PNG, JPG, JPEG 및 WebP를 지원합니다. 모든 참조 이미지를 포함한 전체 요청은 4.5MB 미만을 유지해야 합니다(이미지 총합은 4MB 미만으로 유지). 더 큰 요청은 API에 도달하기 전에 호스팅 플랫폼에서 일반 텍스트 413으로 거부되므로, 먼저 이미지 크기를 조정하거나 압축하세요.
• 최대 참조 이미지 수는 각 모델의 reference_image_limit에 의해 정의됩니다.
• 속도 제한: API 키당 분당 60회의 생성 요청 및 IP 주소당 분당 120회. 모든 응답에는 RateLimit-Limit, RateLimit-Remaining 및 RateLimit-Reset 헤더가 포함되며, 429 응답에는 Retry-After도 포함됩니다.
• 생성을 안전하게 재시도하려면 Idempotency-Key 헤더(최대 120자)를 전송하세요. 동일한 API 키로 동일한 키를 다시 요청하면 요금이 다시 청구되지 않고 기존 생성 결과가 반환됩니다.
• 비동기 모드는 poll_url과 함께 202를 반환합니다. 웹후크는 아직 지원되지 않습니다.