API 레퍼런스

공개 REST API의 전체 스키마예요. Pro 및 Max 플랜에서 사용할 수 있어요. /account/api에서 키를 발급받으세요.

Postman을 선호하시나요? v2.1 컬렉션을 다운로드해 gimg_… 키를 apiKey 변수에 붙여넣으세요.

인증

모든 엔드포인트는 Authorization 헤더에 Bearer 토큰을 받습니다. 토큰은 항상 gimg_로 시작해요.

Authorization: Bearer gimg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

레이트 리밋

키당 시간당 600 요청, 동시 처리 최대 5건. 모든 응답에는 다음 헤더가 포함됩니다:

X-RateLimit-Limit — 600으로 고정
X-RateLimit-Remaining — 현재 윈도우에 남은 호출 수
X-RateLimit-Reset — 윈도우가 리셋되는 epoch 초
Retry-After — 다음 호출까지 남은 초 (429에서만 제공)

멱등성

POST 요청에 Idempotency-Key를 함께 보내 주세요. 같은 키로 두 번 요청하면 새 생성 대신 기존 행을 반환하므로 크레딧이 중복 차감되지 않아요.

POST/api/v1/generate

텍스트→이미지 또는 이미지 편집 생성을 제출합니다. generationId와 함께 즉시 반환되며, /api/v1/generations/:id를 폴링해 결과를 받아 보세요.

Body

promptstring ≤ 4000 chars필수
자연어 설명. 사진가 용어(카메라, 렌즈, 조명)를 사용하면 도움이 돼요.
type"text2img" | "edit"
기본값은 'text2img'예요. 'edit'은 inputImageKeys가 필요해요.
size"1024x1024" | "1024x1536" | "1536x1024"
화면 비율. 기본값은 1024x1024예요.
quality"low" | "medium" | "high"
기본값은 medium이에요. high = HD 2K. low는 Fast(1cr).
n1–4
변형 개수. 기본값은 1이에요.
inputImageKeysstring[] (max 4)
/api/v1/upload가 반환한 R2 키. type=edit일 때 필수예요.

응답

202 Acceptedjson
{ "generationId": "...", "status": "queued" }
400 Bad Requestjson
잘못된 본문이에요. 오류에 Zod 검증 메시지가 포함됩니다.
401 Unauthorizedjson
Bearer 키가 없거나 잘못됐어요.
402 Payment Requiredjson
크레딧이 부족하거나 월간 컴퓨트 한도에 도달했어요.
403 Forbiddenjson
Pro 또는 Max 플랜이 필요해요.
422 Unprocessablejson
콘텐츠 정책에 의해 프롬프트가 차단됐어요.
429 Too Many Requestsjson
레이트 리밋에 도달했어요. Retry-After를 확인하세요.

POST/api/v1/upload

입력 이미지 업로드를 위한 사전 서명된 R2 PUT URL을 받습니다. 두 단계: 이 호출이 URL을 반환하면 해당 URL로 바이트를 직접 PUT하세요.

Body

filenamestring ≤ 200필수
표시용 이름이며, 저장에는 사용되지 않아요.
contentType"image/png" | "image/jpeg" | "image/webp"필수
이 셋 중 하나여야 합니다.
sizenumber (bytes ≤ 10 MB)필수
PUT할 파일 크기. 검증에 사용돼요.

응답 (200)

urlstring
사전 서명된 PUT URL, 5분 후 만료됩니다.
keystring
R2 키 — /api/v1/generate 호출 시 inputImageKeys에 전달하세요.

GET/api/v1/generations/:id

생성의 상태를 폴링합니다. 현재 상태와 함께 즉시 반환됩니다.

응답 (200)

idstring
생성 id예요.
status"queued" | "running" | "succeeded" | "failed" | "blocked"
'blocked' = 콘텐츠 검수가 입력 또는 출력을 거부했어요 (크레딧 환불).
typestring
text2img | edit | upscale | …
outputsArray<{ png, webp, width, height }>
status=succeeded일 때 채워집니다. URL은 공개되며, 불변이고 CDN에 캐시됩니다.
errorstring | null
status=failed 또는 status=blocked일 때 채워집니다.
costCreditsnumber
차감된 크레딧 (blocked 또는 failed인 경우 환불).
createdAt / completedAtISO 8601
타임스탬프.

아웃바운드 웹훅

폴링 대신: HTTPS 엔드포인트를 등록하면 발생 즉시 generation.succeeded와 generation.failed 이벤트를 받아볼 수 있어요. /api/account/webhooks에서 관리하세요.

등록

curl -X POST https://gptimage2.plus/api/account/webhooks \
  -H "Cookie: <your session cookie>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/hooks/gptimg",
    "events": ["generation.succeeded", "generation.failed"],
    "label": "Production app"
  }'
# → { "id": "...", "secret": "whsec_..." }   ← copy this, shown ONCE

이벤트 페이로드

POST https://your-app.com/hooks/gptimg
X-Gptimg-Event: generation.succeeded
X-Gptimg-Signature: <hex sha256 hmac of body>
X-Gptimg-Delivery: <uuid for dedup>
Content-Type: application/json

{
  "event": "generation.succeeded",
  "data": {
    "generationId": "...",
    "type": "text2img",
    "status": "succeeded",
    "outputs": [{ "png": "...", "webp": "...", "width": 1024, "height": 1024 }],
    "createdAt": "2026-04-26T01:23:45.000Z",
    "completedAt": "2026-04-26T01:23:50.000Z"
  }
}

서명 검증

// Node example
import crypto from "crypto";
const expected = crypto
  .createHmac("sha256", process.env.WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");
const ok = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(req.headers["x-gptimg-signature"])
);

타임아웃: 시도당 5초. 2xx가 아닌 응답은 지수 백오프로 최대 3회 재시도합니다 (30초 → 2분 → 10분). 시도 전반에 걸쳐 8회 연속 실패하면 웹훅이 자동 비활성화돼요 — /account/webhooks에서 다시 활성화하세요.