이미지 생성

개요Copy Anchor Link

에이전트는 먼저 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입니다. background 는 auto 또는 opaque 를 허용하며 transparent 는 지원하지 않습니다. size 또는 quality를 생략하면 TokenLab가 auto를 사용합니다. 사용자 지정 size 값은 아래의 유연한 WIDTHxHEIGHT 계약을 따라야 합니다.

input_fidelity는 현재 TokenLab의 gpt-image-2 공개 계약에 포함되지 않습니다. 생략하세요. 보내면 400 unsupported_parameter가 반환됩니다.

모델 동작 참고Copy Anchor Link

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는 text-to-image와 image-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 로 보내지 마세요.
• 이 엔드포인트의 참조 이미지는 JSON image_url / image_urls 또는 multipart image 파일로 보낼 수 있습니다. /v1/images/generations 는 images[] 와 file_id 를 받지 않습니다. /v1/files 참조는 images[].file_id 를 명시적으로 지원하는 /v1/images/edits 모델에서만 사용하세요.

Google 이미지 패밀리에는 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로 유지됩니다.

요청 본문Copy Anchor Link

동기 요청 타임아웃: 일부 이미지 요청은 생성이 완료될 때까지 기다린 뒤 최종 이미지를 inline 으로 반환합니다. 고해상도 또는 고품질 요청은 1분 안팎이거나 그 이상 걸릴 수 있으므로 HTTP 클라이언트 타임아웃을 최소 120s 로 설정하세요. 생성 응답에 status: "pending", task_id, 또는 poll_url 이 포함되어 있으면 반환된 poll_url 을 따라 폴링하세요.

응답Copy Anchor Link

동기 응답Copy Anchor Link

비동기 작업 응답Copy Anchor Link

gpt-image-2 또는 공식 FLUX/BFL 이미지 모델에서 async: true를 설정하면 생성 요청에서 최종 이미지를 기다리지 않고 작업을 생성합니다. 응답에는 status: "pending", task_id, poll_url이 포함됩니다. 작업이 completed 또는 failed가 될 때까지 /v1/tasks/{task_id}를 폴링하세요.

비동기 이미지 작업은 최종 이미지 URL만 반환합니다. 원본 b64_json 이미지 데이터가 필요하면 동기 요청을 사용하세요.

작업 생성 시 예상 금액이 예약될 수 있습니다. 완료된 작업은 실제 사용량으로 정산되며, 실패하거나 시간 초과된 작업은 예약 금액이 해제되거나 환불됩니다.

작업 결과를 받으면 status: "pending"일 때 poll_url 또는 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'];

{
  "model": "gemini-2.5-flash-image",
  "prompt": "A clean editorial product shot of a citrus soda can",
  "aspect_ratio": "16:9"
}

{
  "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"
}

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..."
    }
  ]
}

사용 가능한 모델Copy Anchor Link

현재 이미지 모델, 기능, 가격은 GET /v1/models?recommended_for=image에서 확인하세요.

모델이 항상 동기 또는 항상 비동기라고 하드코딩하지 마세요. 생성 응답이 status: "pending" 를 반환하면 poll_url 을 따라 완료될 때까지 조회하세요.

비동기 응답 처리Copy Anchor Link

이미지 모델의 경우 응답에 status: "pending" 이 포함되어 있는지 항상 확인하세요:

{
  "model": "hy-image-v3.5-preview",
  "prompt": "A yellow lemon on a white table",
  "size": "1024x1024",
  "n": 1,
  "response_format": "url"
}