이미지 생성 (Create Image)

개요Copy Anchor Link

GET /v1/models?recommended_for=image를 사용하여 현재 이미지 모델을 확인한 다음, 선택한 model을 명시적으로 전송하십시오.

gpt-image-2는 토큰 기반 가격이 책정되는 GPT 이미지 모델입니다. TokenLab은 텍스트 입력, 이미지 입력, 보고된 캐시 입력 및 이미지 출력 토큰에 대해 OpenAI의 공식 사용량 산정 방식을 따르며, 이미지당 고정 요금이 부과되지 않습니다.

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 이미지 제품군 모델은 동일한 선택자 계약을 공유하지 않습니다:

• 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)에서 operation: "image-to-image" 및 image_urls와 함께 nano-banana-2, nano-banana-2.1, nano-banana-2-lite 또는 nano-banana-pro를 사용하십시오. 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에서 허용되지 않습니다. /v1/files 참조는 images[].file_id를 문서화하는 /v1/images/edits 모델에 대해서만 생성하십시오.

Google 이미지 제품군의 경우 aspect_ratio를 우선적으로 사용하고, 모델이 명시적으로 지원하는 경우에만 resolution을 전송하십시오.

xAI Grok Imagine 이미지 모델(grok-imagine-image, grok-imagine-image-2.0 및 레거시 grok-imagine-image-pro)은 aspect_ratio와 resolution(1k, 2k)을 지원합니다. grok-imagine-image-pro는 grok-imagine-image-2.0와의 호환성을 위해 유지됩니다.

요청 본문 (Request Body)Copy Anchor Link

동기식 요청 타임아웃: 일부 이미지 요청은 최종 이미지를 인라인으로 반환하며 생성이 완료될 때까지 대기합니다. 고해상도 또는 고품질 요청은 1분 이상 소요될 수 있으므로 HTTP 클라이언트 타임아웃을 최소 120s로 설정하십시오. 생성 응답에 status: "pending", task_id 또는 poll_url이 포함된 경우, 반환된 poll_url을 따르십시오.

응답 (Response)Copy Anchor Link

인라인 응답 (Inline Response)Copy Anchor Link

비동기 작업 응답 (Async Task Response)Copy Anchor Link

gpt-image-2 또는 공식 FLUX/BFL 이미지 모델과 함께 async: true를 설정하면 생성 요청에서 최종 이미지를 기다리는 대신 작업을 생성합니다. 응답에는 status: "pending", task_id 및 poll_url이 포함됩니다. 작업이 completed 또는 failed 상태가 될 때까지 poll_url을 폴링하십시오.

비동기 이미지 작업은 최종 이미지 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": "nano-banana",
  "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..."
    }
  ]
}

모델 선택 (Choose a Model)Copy Anchor Link

현재 가용성, 기능 및 가격은 GET /v1/models?recommended_for=image를 쿼리하거나 모델 페이지를 참조하십시오.

모델을 항상 동기식 또는 항상 비동기식으로 하드코딩하지 마십시오. 생성 응답이 status: "pending"을 반환하면 poll_url을 따라 완료될 때까지 폴링하십시오.

작업 기반 응답 처리 (Handling Task-Based Responses)Copy Anchor Link

이미지 모델의 경우 응답에 status: "pending" / status: "processing"이 포함되어 있는지 항상 확인하십시오:

import requests
import time

def generate_image(prompt, model="gpt-image-2"):
    # 이미지 생성 요청
    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()

    # 작업 기반인지 확인
    if data.get("status") in ("pending", "processing"):
        task_id = data["task_id"]
        poll_url = data.get("poll_url")
        print(f"Image task started: {task_id}")

        # 결과 폴링
        while True:
            status_resp = requests.get(
                f"https://api.tokenlab.sh{poll_url}" if poll_url else 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)
    else:
        # 인라인 응답
        return data["data"][0]["url"]

# 사용 예시
url = generate_image("a beautiful sunset over mountains", model="gpt-image-2")
print(f"Generated image: {url}")

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