개요
에이전트는 먼저GET /v1/models?recommended_for=image 로 현재 추천 이미지 모델 후보를 확인한 뒤, 선택한 model 을 이 엔드포인트에 명시적으로 전달하세요.
gpt-image-2 는 token 단위로 과금되는 GPT Image 모델입니다. TokenLab 는 OpenAI 공식 usage 세부 내역에 따라 텍스트 입력, 이미지 입력, 보고된 캐시 입력, 이미지 출력 token 을 정산하며, 고정 이미지 단가 모델로 처리하지 않습니다.
gpt-image-2 이미지 생성에서 지원되는 공개 파라미터는 prompt, n, size, quality, response_format, async, background, output_format, output_compression 또는 compression, moderation, user입니다. size 또는 quality를 생략하면 TokenLab가 auto를 사용합니다. 사용자 지정 size 값은 아래의 유연한 WIDTHxHEIGHT 계약을 따라야 합니다.
input_fidelity는 현재 TokenLab의 gpt-image-2 공개 계약에 포함되지 않습니다. 생략하세요. 보내면 400 unsupported_parameter가 반환됩니다.
모델 동작 참고
Google Gemini image-family 모델은 같은 선택자 계약을 공유하지 않습니다.gemini-3.1-flash-image,gemini-3-pro-image,nano-banana-pro는 공개 text-to-image 및 image-edit/image-to-image 작업에서aspect_ratio와resolution(1k,2k,4k) 을 지원합니다.nano-banana-2는 현재 TokenLab 계약에서 text-to-image에만aspect_ratio와resolution(1k,2k,4k) 을 지원합니다.gemini-2.5-flash-image,nano-banana,nano-banana-edit는aspect_ratio를 지원하지만 공개resolution선택은 노출하지 않습니다.- Nano Banana 참조 이미지 요청은 이 엔드포인트(
/v1/images/generations)에서nano-banana-edit또는nano-banana-pro를 사용하고operation: "image-to-image"와image_urls를 보내세요. Nano Banana 참조 이미지 요청을/v1/images/edits로 보내지 마세요. - Nano Banana image-to-image 요청에서
nano-banana-pro는resolution(1k,2k,4k) 을 포함할 수 있습니다.nano-banana-edit에서는 생략해야 합니다.nano-banana와nano-banana-2는 현재 모델 세부정보에서 text-to-image 모델입니다. - 이 엔드포인트의 참조 이미지는 JSON
image_url/image_urls또는 multipartimage파일로 보낼 수 있습니다./v1/images/generations는images[]와file_id를 받지 않습니다./v1/files참조는images[].file_id를 명시적으로 지원하는/v1/images/edits모델에서만 사용하세요.
aspect_ratio 를 우선 사용하고, 모델이 명시적으로 지원할 때만 resolution 을 보내세요.
xAI Grok Imagine 이미지 모델(grok-imagine-image, grok-imagine-image-quality, legacy grok-imagine-image-pro)은 aspect_ratio 와 resolution (1k, 2k) 을 지원합니다. grok-imagine-image-pro 는 grok-imagine-image-quality 의 호환 ID로 유지됩니다.
요청 본문
동기 요청 타임아웃: 일부 이미지 요청은 생성이 완료될 때까지 기다린 뒤 최종 이미지를 inline 으로 반환합니다. 고해상도 또는 고품질 요청은 1분 안팎이거나 그 이상 걸릴 수 있으므로 HTTP 클라이언트 타임아웃을 최소120s 로 설정하세요. 생성 응답에 status: "pending", task_id, 또는 poll_url 이 포함되어 있으면 반환된 poll_url 을 따라 폴링하세요.
사용할 모델(예:
gpt-image-2, flux-pro, qwen-image-plus, nano-banana-pro). 현재 추천 목록은 GET /v1/models?recommended_for=image 로 확인하세요.원하는 이미지에 대한 텍스트 설명입니다.
image-to-image 생성에 사용할 공개 HTTPS 참조 이미지 URL입니다. Nano Banana 참조 이미지 요청은
operation 을 image-to-image 로 설정하세요. nano-banana-pro 는 resolution 을 포함할 수 있고, nano-banana-edit 는 생략해야 합니다.공개 HTTPS 참조 이미지 URL 배열입니다. JSON 요청에서 하나 이상의 참조 이미지를 보낼 때 사용합니다. 이 엔드포인트는
file_id 와 images[] 를 지원하지 않습니다.기본 입력 이미지와 참조 이미지를 구분하는 공급자를 위한 추가 모델별 참조 이미지 URL입니다.
image-to-image 생성을 위한 multipart 참조 이미지 파일입니다. 원본 이미지가 비공개이거나 헤더 인증이 필요할 때 직접 업로드를 사용하세요. /v1/files 의
file_id 와는 다르며, 이 엔드포인트는 file_id 를 받지 않습니다.생성할 이미지 수입니다 (1-10, 모델에 따라 다름).
이미지 크기입니다. OpenAI 스타일 이미지 계열 및 정확한 픽셀 크기를 받는 다른 모델에 사용합니다.
gpt-image-2 의 size 는 auto 또는 WIDTHxHEIGHT 를 허용합니다. 사용자 지정 크기는 두 변이 모두 16의 배수여야 하고, 가장 긴 변은 3840px 이하여야 하며, 긴 변/짧은 변 비율은 3:1 이하여야 하고, 총 픽셀 수는 655,360 이상 8,294,400 이하이어야 합니다. aspect_ratio 와 resolution 은 현재 TokenLab 의 gpt-image-2 모델 세부정보에 포함되지 않습니다..Google Gemini 이미지 계열에서는 size 가 호환 alias 로 처리되어 모델의 공개 aspect_ratio 계약과, 지원되는 경우 resolution 계약으로 매핑됩니다. 이 모델들에는 aspect_ratio 를 직접 보내는 것을 권장합니다.모델별 종횡비 선택값입니다.Google 이미지 패밀리에서 자주 쓰는 값은
1:1, 16:9, 9:16, 3:2, 2:3 입니다.모델별 출력 해상도 선택값입니다.
gemini-3.1-flash-image 와 gemini-3-pro-image 는 text-to-image 및 image-edit에서, nano-banana-pro 는 text-to-image 및 image-to-image에서, nano-banana-2 는 text-to-image에서만 지원합니다. 일반적인 값은 1k, 2k, 4k 입니다. 모델이 명시적으로 문서화하지 않았다면 비율만 지원하는 Gemini 이미지 계열에는 보내지 마세요. xAI Grok Imagine 이미지 모델에는 1k 또는 2k 를 사용하세요.이미지 품질입니다.
gpt-image-2 같은 GPT Image 모델은 auto, low, medium, high 를 사용합니다. 다른 이미지 계열은 제공자별 값을 사용할 수 있으므로 기본값이 아닌 값을 보내기 전에 선택한 모델 메타데이터를 확인하세요.응답 형식입니다:
url 또는 b64_json. 기본값은 url입니다.Azure Official 또는 Azure-compatible gpt-image-2 요청에서는 TokenLab가 이미지 결과를 b64_json으로 받습니다. url 요청에서는 각 이미지를 CDN에 업로드한 뒤 data[].url을 반환합니다. CDN 스토리지를 사용할 수 없거나 업로드가 실패하면 Base64 응답으로 바꾸지 않고 요청을 실패시킵니다. b64_json 요청에서는 원본 Base64를 반환합니다.gpt-image-2 또는 공식 FLUX/BFL 이미지 모델에서 true로 설정하면 먼저 작업을 생성합니다. 완료된 비동기 이미지 작업은 요청한 response_format과 관계없이 URL을 반환합니다. b64_json이 필요하면 동기 요청을 사용하세요.선택적 스타일 지정자입니다. 선택한 모델이 명시적으로 문서화한 경우에만 보내세요. 모델 메타데이터에 달리 표시되어 있지 않다면
gpt-image-2 에는 생략하세요.최종 사용자를 식별하는 고유 ID입니다.
응답
동기 응답
생성 시점의 Unix timestamp입니다.
생성된 이미지 배열입니다.각 객체는 다음을 포함합니다:
url(string): 생성된 이미지의 URLb64_json(string): Base64로 인코딩된 이미지 (요청한 경우)revised_prompt(string): 선택한 모델이 반환한 선택적 프롬프트 수정본
비동기 작업 응답
gpt-image-2 또는 공식 FLUX/BFL 이미지 모델에서 async: true를 설정하면 생성 요청에서 최종 이미지를 기다리지 않고 작업을 생성합니다. 응답에는 status: "pending", task_id, poll_url이 포함됩니다. 작업이 completed 또는 failed가 될 때까지 /v1/tasks/{task_id}를 폴링하세요.
비동기 이미지 작업은 최종 이미지 URL만 반환합니다. 원본 b64_json 이미지 데이터가 필요하면 동기 요청을 사용하세요.
작업 생성 시 예상 금액이 예약될 수 있습니다. 완료된 작업은 실제 사용량으로 정산되며, 실패하거나 시간 초과된 작업은 예약 금액이 해제되거나 환불됩니다.
생성 시각의 Unix 타임스탬프입니다.
폴링용 고유 작업 식별자.
초기 상태:
pending.결과를 폴링하기 위한 상대 URL이며, 예를 들어
/v1/tasks/{id}입니다.작업이 pending인 동안에는 비어 있습니다. 완료된 이미지 작업은 생성된 이미지 URL을
data[].url에 반환합니다.status: "pending"일 때 poll_url 또는 GET /v1/tasks/{task_id}를 사용해 결과를 가져오세요.
사용 가능한 모델
아래는 현재 예시 모델이며 고정 카탈로그가 아닙니다. 최신 제공 여부와 가격은GET /v1/models?recommended_for=image 또는 Models 페이지에서 확인하세요.
| 모델 | 유형 | 기능 |
|---|---|---|
gpt-image-2 | 인라인 또는 작업 기반 | 토큰 단위 과금 GPT Image 모델, 유연한 크기 |
flux-pro | 작업 기반인 경우가 많음 | 사실적인 이미지, 고품질 |
qwen-image-plus | 작업 기반인 경우가 많음 | 강한 텍스트 렌더링과 프롬프트 준수 |
nano-banana-pro | 작업 기반인 경우가 많음 | 참조 이미지 워크플로와 고해상도 출력 |
grok-imagine-image | 작업 기반인 경우가 많음 | xAI 이미지 생성, 종횡비와 해상도 선택 지원 |
ideogram-v3 | 작업 기반인 경우가 많음 | 강한 텍스트 렌더링 |
status: "pending" 를 반환하면 poll_url 을 따라 완료될 때까지 조회하세요.
비동기 응답 처리
이미지 모델의 경우 응답에status: "pending" 이 포함되어 있는지 항상 확인하세요: