이미지
이미지 생성
주어진 프롬프트를 바탕으로 이미지를 생성합니다
개요
GET /v1/models?recommended_for=image를 사용하여 현재 이미지 모델 목록을 가져온 다음, 선택한 model을 명시적으로 전송합니다.
각 모델은 고유한 작업과 필드를 지원합니다. GET /v1/models/{model}(모델 가져오기)는 tokenlab.request_format_summary.request_endpoint_by_operation에서 각 작업별 엔드포인트를 제공하며, tokenlab.request_format_details.operation_constraints에서 각 작업에 허용되는 필드, 값 및 제한 사항을 제공합니다. 모델 목록에 정의되지 않은 필드는 400 unsupported_parameter를 반환할 수 있습니다. 잘못된 엔드포인트로 전송된 작업은 400 unsupported_endpoint를 반환합니다.
이미지 작업 및 결과:
- 지원 파라미터에
async가 나열된 모델은 작업을 먼저 생성할 수 있습니다.async: true를 전송한 후GET /v1/tasks/{id}를 폴링하세요. - 이미지 링크는 30일 동안 저장됩니다. 데이터 보존을 참조하세요.
- 타임아웃 발생 후 생성 요청을 안전하게 재시도하려면
Idempotency-Key헤더를 전송하세요. 멱등성 키를 사용한 안전한 재시도를 참조하세요.
gpt-image-2는 토큰 요금제 기반의 GPT Image 모델입니다. TokenLab은 텍스트 입력, 이미지 입력, 보고된 캐시 입력 및 이미지 출력 토큰에 대해 OpenAI의 공식 사용량 세부 구분을 따르며, 이미지당 고정 요금 모델로 청구되지 않습니다.
gpt-image-2 이미지 생성 시 지원되는 공개 파라미터는 prompt, n, size, quality, response_format, async, background, output_format, output_compression 또는 compression, moderation, user입니다. background는 auto 또는 opaque를 허용하며, transparent는 지원되지 않습니다. TokenLab이 auto를 사용하도록 하려면 size 또는 quality를 생략하세요. 커스텀 size 값은 아래에 설명된 유연한 WIDTHxHEIGHT 규칙을 따라야 합니다.
input_fidelity는 현재 TokenLab의 gpt-image-2 지원 필드에 포함되지 않습니다. 이 필드를 생략하지 않으면 요청 시 400 unsupported_parameter가 반환됩니다.
SVG 및 GIF 출력
gpt-image-2.6-flare 및 gpt-image-2.6-sunburst는 래스터 이미지 대신 SVG 또는 애니메이션 GIF를 반환할 수 있습니다. 다른 모델은 이러한 형식을 지원하지 않습니다.
- SVG:
output_format: "svg"및svg: {"model": "..."}를 전송합니다. 이미지 모델이 먼저 참조 이미지를 생성한 다음, 작성자(author) 모델이 이를 바탕으로 SVG를 작성합니다.svg.model은 필수 항목이며, 모델 세부 정보의parameter_options(svg.model)에서 허용되는 값을 확인할 수 있습니다.svg.reasoning.effort를 함께 전송할 수도 있습니다. SVG는 이 엔드포인트에서만 작동하며,n: 1설정이 필요하고partial_images또는output_compression은 사용할 수 없습니다. - GIF:
output_format: "gif"를 전송합니다.frame_count(216, 기본값 9)는 프레임 수를 설정하고,2000, 기본값 200)는 각 프레임의 지속 시간을 설정합니다.frame_duration_ms(20size는 단일 프레임의 크기입니다. GIF는partial_images또는output_compression을 지원하지 않습니다.
결과는 다른 이미지와 마찬가지로 data[].b64_json 또는 data[].url에 포함됩니다. SVG는 UTF-8 XML 텍스트로 디코딩하여 .svg로 저장하고, GIF는 .gif로 저장하십시오.
과금: 이미지 토큰은 해당 모델의 토큰 가격으로 청구되며, GIF 프레임은 이미지 출력 토큰으로 계산됩니다. SVG 요청 시에는 작성자 모델의 토큰도 함께 청구되며, 이는 응답의 svg_usage에 보고됩니다. 해당 비용은 모델 페이지에 명시된 SVG 작성 가격을 따릅니다.
모델 동작 참고 사항
Google Gemini 이미지 계열 모델은 동일한 선택자(selector) 규칙을 공유하지 않습니다:
gemini-3.1-flash-image,gemini-nano-banana-2.1,gemini-3-pro-image,nano-banana-2.1,nano-banana-pro는 공개 텍스트-이미지(text-to-image), 이미지-이미지(image-to-image) 및 이미지 편집(image-edit) 작업에 대해aspect_ratio와resolution(1k,2k,4k)을 지원합니다.nano-banana-2는 텍스트-이미지 및 이미지-이미지 생성 모두에 대해aspect_ratio및resolution(1k,2k,4k)을 지원합니다.gemini-3.1-flash-lite-image및nano-banana-2-lite는1k해상도에서만 텍스트-이미지, 이미지-이미지 및 이미지 편집을 지원합니다.nano-banana는aspect_ratio를 지원하지만 공개resolution선택을 제공하지 않습니다.gemini-3.1-flash-image,gemini-nano-banana-2.1,gemini-3.1-flash-lite-image또는gemini-3-pro-image로 이미지-이미지 작업을 수행하려면 이 엔드포인트에서operation: "image-to-image"와 참조 이미지를 사용하세요. 이 모델들에 대한 이미지 편집 요청은/v1/images/edits로 전송해야 합니다.- Nano Banana 참조 이미지 요청의 경우, 이 엔드포인트(
/v1/images/generations)에서nano-banana-2,nano-banana-2.1,nano-banana-2-lite또는nano-banana-pro를operation: "image-to-image"및image_urls와 함께 사용하세요.nano-banana-2,nano-banana-2.1,nano-banana-2-lite및nano-banana-pro의 이미지 편집 요청 또한 이 엔드포인트에서operation: "image-edit"과 함께 사용합니다. Nano Banana 참조 이미지 요청을/v1/images/edits로 전송하지 마세요. - 이 엔드포인트의 참조 이미지는 JSON
image_url/image_urls또는 멀티파트image파일로 제공할 수 있습니다.images[]및file_id는/v1/images/generations에서 지원되지 않습니다.images[].file_id가 문서화된/v1/images/edits모델에 대해서만/v1/files참조를 생성하세요.
Google 이미지 계열의 경우 aspect_ratio 사용을 권장하며, 모델이 명시적으로 지원하는 경우에만 resolution을 전송하세요.
xAI Grok Imagine 이미지 모델(grok-imagine-image 및 grok-imagine-image-2.0)은 aspect_ratio와 resolution(1k, 2k)을 지원합니다. 텍스트-이미지는 이 엔드포인트를 사용합니다. 해당 모델들의 이미지-이미지 및 이미지 편집 요청은 /v1/images/edits를 사용합니다.
hy-image-v3.5-preview는 이 엔드포인트에서 텍스트를 통해 요청당 1개의 1024x1024 이미지를 생성하며, response_format: "url"만 지원합니다. 참조 이미지 편집은 /v1/images/edits에서 수행합니다.
요청 본문
동기식 요청 타임아웃: 일부 이미지 요청은 최종 이미지를 인라인으로 반환하며 생성이 완료될 때까지 대기합니다. 고해상도 또는 고품질 요청은 1분 가까이 또는 그 이상 소요될 수 있으므로 HTTP 클라이언트 타임아웃을 최소 120s로 설정하세요. 생성 응답에 status: "pending", task_id 또는 poll_url이 포함된 경우 대신 GET /v1/tasks/{task_id}를 폴링하세요.
사용할 모델입니다(예: gpt-image-2, flux-pro-1.1 또는 nano-banana-pro). 현재 권장 목록을 확인하려면 GET /v1/models?recommended_for=image를 쿼리하세요.
원하는 이미지에 대한 텍스트 설명으로, 최대 32,000자입니다. 세부 정보에 prompt가 나열된 모든 모델에 필수입니다.
text-to-image, image-to-image 또는 image-edit입니다. 생략할 경우, 요청에 참조 이미지가 있으면 image-to-image가 되고, 그렇지 않으면 text-to-image가 됩니다. nano-banana-pro와 같이 편집 작업이 이 엔드포인트에 있는 모델의 경우 image-edit로 설정하세요. 참조 이미지가 포함된 text-to-image는 400 invalid_parameter를 반환합니다.
이미지-이미지 생성을 위한 공개 이미지 URL입니다. Nano Banana 참조 이미지 요청의 경우 operation을 image-to-image로 설정하세요. nano-banana-pro에는 resolution이 포함될 수 있습니다.
공개 참조 이미지 URL 배열로, 최대 16개까지 가능합니다. JSON 요청에서 하나 이상의 참조 이미지를 사용할 때 이 필드를 사용하세요. file_id 및 images[]는 이 엔드포인트에서 지원되지 않습니다.
기본 입력과 참조를 구분하는 모델을 위한 추가 참조 이미지 URL(최대 16개)입니다.
이미지-이미지 생성을 위한 멀티파트 참조 이미지 파일입니다. 소스 이미지가 비공개이거나 헤더로 보호되는 경우 사용하세요. 이는 이 엔드포인트에서 지원되지 않는 /v1/files file_id와는 다릅니다.
1생성할 이미지 수입니다(1-10, 모델에 따라 다름).
이미지 크기입니다. OpenAI 스타일의 이미지 계열 및 정확한 픽셀 크기를 허용하는 기타 모델에 사용하세요.
gpt-image-2의 경우 size는 auto 또는 WIDTHxHEIGHT를 지원합니다. 커스텀 크기는 두 차원 모두 16의 배수여야 하며, 가장 긴 변은 최대 3840px, 가로/세로 비율은 최대 3:1, 총 픽셀 수는 655,360에서 8,294,400 사이여야 합니다. aspect_ratio 및 resolution은 현재 gpt-image-2의 TokenLab 모델 세부 정보에 포함되지 않습니다.
해상도 등급이 있는 Google 이미지 모델(gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image, gemini-3.1-flash-lite-image, nano-banana-2, nano-banana-2.1 및 nano-banana-pro)의 경우, size는 모델의 크기 표에 명시된 출력 크기(예: 1K의 16:9인 1376x768) 또는 해상도 등급(1K, 2K, 4K)을 허용합니다. TokenLab은 등급을 resolution으로 전송하므로 요청 및 요금은 resolution을 사용했을 때와 동일합니다. 모델이 지원하지 않는 등급(예: gemini-3.1-flash-lite-image의 2K)이나 resolution과 다른 등급을 지정하면 400 응답과 함께 invalid_image_size_contract 코드 및 해당 모델의 allowed_resolutions가 반환됩니다. 이러한 모델의 경우 권장되는 형식은 aspect_ratio와 resolution의 조합입니다.
모델에 따라 달라지는 가로세로 비율 선택자입니다.
자주 사용되는 Google 이미지 계열 값에는 1:1, 16:9, 9:16, 3:2, 2:3이 있습니다.
모델에 따라 달라지는 출력 해상도입니다. gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image, nano-banana-2, nano-banana-2.1 및 nano-banana-pro는 1k, 2k, 4k를 지원하며, Grok Imagine 이미지 모델은 1k, 2k를 지원합니다. 선택한 모델과 작업에서 명시적으로 지원하지 않는 한 이 필드를 생략하세요.
이미지 품질입니다. gpt-image-2와 같은 GPT Image 모델은 auto, low, medium, high를 사용합니다. 다른 모델은 다른 값을 사용할 수 있으므로 기본값이 아닌 값을 보내기 전에 모델 세부 정보를 확인하세요.
이미지의 파일 형식: png, jpeg 또는 webp. gpt-image-2.6-flare 및 gpt-image-2.6-sunburst는 svg 및 gif도 지원합니다. SVG 및 GIF 출력을 참조하세요.
SVG 설정으로, output_format: "svg"일 때만 사용 가능합니다. model (필수)은 SVG를 작성할 작성자 모델을 선택합니다. reasoning.effort는 선택적으로 추론 강도를 설정합니다.
9GIF 프레임 수로, 2에서 16까지 설정 가능합니다. output_format: "gif"일 때만 사용 가능합니다.
200각 GIF 프레임의 지속 시간(밀리초 단위)으로, 20에서 2000까지 설정 가능합니다. output_format: "gif"일 때만 사용 가능합니다.
이미지 반환 형식: url 또는 b64_json.
- 생략 시: 모델이 이미지 바이트를 반환할 때 각 이미지는
data[].b64_json에 포함되며, TokenLab이 이미지를 저장한 경우data[].url에도 포함됩니다. 모델이 링크를 반환할 때는 각 이미지가data[].url에 포함됩니다. url: 각 이미지가data[].url에만 포함됩니다.b64_json: 각 이미지가 Base64 데이터로data[].b64_json에만 포함됩니다.
링크는 TokenLab 미디어 결과 URL입니다. 30일 동안 유효합니다. 데이터 보존을 참조하세요.
falsetrue로 설정하면 작업을 먼저 생성합니다. async를 지원하는 매개변수로 나열된 모델(예: gpt-image-2, flux-pro-1.1, nano-banana-pro, seedream-5.0-lite)에서만 허용됩니다. 다른 모델의 경우 요청 시 400 unsupported_async_mode가 반환됩니다. 완료된 비동기 이미지 작업은 요청한 response_format과 관계없이 URL을 반환합니다. b64_json이 필요한 경우에는 동기식 요청을 사용하십시오.
선택적 스타일 선택자입니다. 선택한 모델에서 명시적으로 문서화된 경우에만 전송하세요. 모델 메타데이터에 별도의 언급이 없는 한 gpt-image-2의 경우 생략하세요.
최종 사용자의 고유 식별자입니다.
일부 모델은 negative_prompt, seed, width, height, steps, guidance_scale 또는 mask_url과 같은 필드도 지원합니다. 모델 세부 정보에 나열되어 있는 경우에만 전송하세요. stream: true는 지원되지 않으며 400 unsupported_parameter를 반환합니다.
응답
인라인 응답
생성 시점의 Unix 타임스탬프입니다.
생성된 이미지 배열입니다.
각 객체에는 다음이 포함됩니다:
url(string): 이미지의 TokenLab 미디어 결과 URL로, 30일간 유효합니다.response_format이b64_json일 때는 제공되지 않습니다.response_format이 생략된 경우 TokenLab이 이미지를 저장하지 못했다면 누락될 수 있습니다.b64_json(string): Base64 이미지 데이터입니다.response_format이b64_json이거나, 생략되었으나 모델이 이미지 바이트를 반환할 때 제공됩니다.revised_prompt(string): 선택한 모델에서 제공하는 경우 반환되는 수정된 프롬프트입니다.
gpt-image-2와 같은 토큰 요금제 모델의 토큰 수(input_tokens, output_tokens, total_tokens 및 세부 정보)입니다(제공 가능한 경우).
SVG author 모델의 토큰 수(model, input_tokens, output_tokens, reasoning_tokens, total_tokens)입니다. SVG 출력 시에만 제공됩니다. 이 토큰들은 usage에 포함되지 않으며, SVG 저작 비용으로 청구됩니다.
비동기 작업 응답
지원하는 모델에서 async: true를 설정하면 생성 요청에서 최종 이미지를 기다리는 대신 작업을 생성합니다. 응답에는 status: "pending", task_id 및 poll_url이 포함됩니다. 작업이 completed 또는 failed 상태에 도달할 때까지 /v1/tasks/{task_id}를 폴링하세요.
비동기 이미지 작업은 최종 이미지 URL만 반환합니다. 원시 b64_json 이미지 데이터가 필요한 경우 동기식 요청을 사용하세요.
작업이 생성될 때 예상 금액이 청구 예약될 수 있습니다. 완료된 작업은 실제 사용량에 따라 청구되며, 실패하거나 타임아웃된 작업은 예약이 해제되거나 환불됩니다.
생성 시점의 Unix 타임스탬프입니다.
폴링을 위한 고유 작업 식별자입니다.
초기 상태: pending.
결과를 폴링하기 위한 상대 URL입니다(예: /v1/tasks/{id}).
작업이 대기 중인 동안에는 비어 있습니다. 완료된 이미지 작업은 data[].url에 생성된 이미지 URL을 반환합니다.
status: "pending"을 수신하면 GET /v1/tasks/{task_id}를 호출하여 결과를 가져옵니다.
요청
curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-pro-image",
"prompt": "A cinematic portrait of a white cat sitting on a rainy windowsill",
"aspect_ratio": "16:9",
"resolution": "2k"
}'from openai import OpenAI
client = OpenAI(
api_key="sk-your-api-key",
base_url="https://api.tokenlab.sh/v1"
)
response = client.images.generate(
model="gemini-3-pro-image",
prompt="A cinematic portrait of a white cat sitting on a rainy windowsill",
extra_body={"aspect_ratio": "16:9", "resolution": "2k"}
)
print(response.data[0].url)import OpenAI from 'openai';
const client = new OpenAI({
apiKey: 'sk-your-api-key',
baseURL: 'https://api.tokenlab.sh/v1'
});
const response = await client.images.generate({
model: 'gemini-3-pro-image',
prompt: 'A cinematic portrait of a white cat sitting on a rainy windowsill',
aspect_ratio: '16:9',
resolution: '2k'
});
console.log(response.data[0].url);<?php
$ch = curl_init('https://api.tokenlab.sh/v1/images/generations');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Authorization: Bearer sk-your-api-key'
],
CURLOPT_POSTFIELDS => json_encode([
'model' => 'gemini-3-pro-image',
'prompt' => 'A cinematic portrait of a white cat sitting on a rainy windowsill',
'aspect_ratio' => '16:9',
'resolution' => '2k'
])
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
echo $data['data'][0]['url'];비율만 지정하는 이미지 계열 예시: nano-banana의 경우 aspect_ratio를 전송하되 resolution은 생략합니다:
{
"model": "nano-banana",
"prompt": "A clean editorial product shot of a citrus soda can",
"aspect_ratio": "16:9"
}Nano Banana Pro 참조 이미지 예시: 요청을 /v1/images/edits가 아닌 /v1/images/generations로 전송합니다. resolution은 선택 사항이며 1k, 2k 또는 4k로 설정할 수 있습니다:
{
"model": "nano-banana-pro",
"prompt": "Create a clean cinematic character image based on the reference images",
"operation": "image-to-image",
"image_urls": ["https://example.com/reference-1.png"],
"aspect_ratio": "1:1",
"resolution": "2k"
}비공개 또는 로컬 소스 이미지에 대한 직접 멀티파트 업로드 예시입니다. /v1/images/generations에 file_id를 전달하지 마세요:
curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-F "model=nano-banana-pro" \
-F "prompt=Create a clean cinematic character image based on this reference" \
-F "operation=image-to-image" \
-F "image=@reference.png" \
-F "aspect_ratio=1:1" \
-F "resolution=2k"응답
{
"created": 1706000000,
"data": [
{
"url": "https://...",
"revised_prompt": "A fluffy white cat with bright eyes sitting peacefully on a wooden windowsill, watching raindrops stream down the glass window..."
}
]
}오류
요청 오류는 error.code와 함께 400(업로드 용량 초과 시 413)을 반환합니다. 이미지 요청의 일반적인 코드:
| 코드 | 원인 |
|---|---|
unsupported_parameter | 모델에 해당 필드가 없거나 stream이 true인 경우 |
unsupported_operation | 모델에 해당 operation이 없는 경우 |
unsupported_endpoint | 해당 모델의 작업이 /v1/images/edits와 같은 다른 엔드포인트에 있는 경우 |
unsupported_async_mode | 모델이 async: true를 지원하지 않는 경우 |
invalid_resolution, invalid_aspect_ratio, invalid_parameter_value, too_many_items | 값이 모델이 허용하는 범위를 벗어난 경우입니다. 오류 메시지에 허용되는 값이 명시됩니다 |
invalid_image_size_contract | 모델이 지원하지 않는 size나 등급이거나, resolution과 충돌하는 경우 |
prompt_too_long | 프롬프트가 모델 허용 한도보다 긴 경우 |
request_too_large, file_too_large | 업로드가 크기 제한(파일당 50 MiB, 모든 입력 합산 200 MiB)을 초과한 경우 |
잔액(402), 전송률 제한(429) 및 재시도 규칙에 대한 자세한 내용은 오류 처리를 참조하세요.
모델 선택
현재 제공 여부, 기능 및 가격을 확인하려면 GET /v1/models?recommended_for=image를 쿼리하거나 모델 페이지를 참조하세요.
모델을 항상 동기식이거나 항상 비동기식인 것으로 하드코딩하지 마세요. async: true가 없는 요청도 여전히 status: "pending"을 반환할 수 있습니다. 생성 응답에 status: "pending" 또는 status: "processing"이 포함되어 있으면 완료될 때까지 GET /v1/tasks/{task_id}를 폴링하세요.
작업 기반 응답 처리
이미지 모델의 경우 응답에 status: "pending" / status: "processing"이 포함되어 있는지 항상 확인하세요:
import requests
import time
def generate_image(prompt, model="gpt-image-2"):
# Create image request
response = requests.post(
"https://api.tokenlab.sh/v1/images/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={"model": model, "prompt": prompt, "async": True},
timeout=120
)
response.raise_for_status()
data = response.json()
# Check if task-based
if data.get("status") in ("pending", "processing"):
task_id = data["task_id"]
print(f"Image task started: {task_id}")
# Poll for result
deadline = time.time() + 600
while time.time() < deadline:
status_resp = requests.get(
f"https://api.tokenlab.sh/v1/tasks/{task_id}",
headers={"Authorization": "Bearer sk-your-api-key"},
timeout=30
)
status_resp.raise_for_status()
status_data = status_resp.json()
if status_data["status"] == "completed":
return status_data["data"][0]["url"]
elif status_data["status"] == "failed":
raise Exception(status_data.get("error", "Generation failed"))
time.sleep(3)
raise TimeoutError(f"Image task {task_id} did not finish in time")
else:
# Inline response
return data["data"][0]["url"]
# Usage
url = generate_image("a beautiful sunset over mountains", model="gpt-image-2")
print(f"Generated image: {url}")Hy Image 3.5 Preview 예시입니다. size 1024x1024 및 n 1만 지원합니다:
{
"model": "hy-image-v3.5-preview",
"prompt": "A yellow lemon on a white table",
"size": "1024x1024",
"n": 1,
"response_format": "url"
}인증
BearerAuth API 키 인증입니다. Dashboard > API > API Keys에서 API 키를 생성하거나 관리하십시오.
위치: header
헤더
요청별 전송 정책입니다. API 키 및 Workspace 기본값을 재정의합니다. 자동으로 TokenLab Verified를 먼저 시도하며, 출력, 요청 수락 또는 영구 리소스 생성 전에 Official 전용으로 한 번 전환될 수 있습니다.
허용 값
- "auto"
- "verified"
- "official"
이미지 요청이 작업을 생성한 경우 안전하게 재시도할 수 있게 하는 선택적 키입니다. 각 요청마다 UUID와 같은 새로운 고유 값을 전송하십시오. 동일한 키와 동일한 본문으로 재시도하면 해당 작업이 반환되며, 두 번째 작업이 생성, 발송 또는 청구되지 않습니다. 이미지를 직접 반환하는 요청의 경우, 동일한 키로 재시도하면 이미지 대신 작업 상태가 반환되거나 idempotent_response_not_replayable과 함께 409가 반환될 수 있습니다. 이미 수락된 키와 다른 본문을 전송하면 거부되며, 이 경우의 상태 코드와 오류 코드는 보장되지 않습니다. 255자를 초과하는 키는 무시되며, 해당 요청은 멱등성 보호를 받지 못합니다. 멱등성 키를 사용한 안전한 재시도를 참조하십시오.
1 <= length <= 255응답
application/json
application/json
application/json
application/json
application/json
application/json
application/json