Create Image

OverviewCopy Anchor Link

Use GET /v1/models?recommended_for=image to get current image models, then send the selected model explicitly.

gpt-image-2 is a token-priced GPT Image model. TokenLab follows OpenAI's official usage breakdown for text input, image input, reported cached input, and image output tokens; it is not billed as a fixed per-image model.

For gpt-image-2 image generation, supported public parameters are prompt, n, size, quality, response_format, async, background, output_format, output_compression or compression, moderation, and user. background accepts auto or opaque; transparent is not supported. Omit size or quality to let TokenLab use auto; custom size values must use the flexible WIDTHxHEIGHT contract documented below.

input_fidelity is not part of the current TokenLab supported fields for gpt-image-2; omit it or the request returns 400 unsupported_parameter.

Model behavior notesCopy Anchor Link

Google Gemini image-family models do not share the same selector contract:

• gemini-3.1-flash-image, gemini-3-pro-image, and nano-banana-pro support aspect_ratio plus resolution (1k, 2k, 4k) for their public text-to-image and image-edit/image-to-image operations.
• nano-banana-2 supports aspect_ratio and resolution (1k, 2k, 4k) for both text-to-image and image-to-image generation.
• gemini-2.5-flash-image, nano-banana, and nano-banana-edit support aspect_ratio but do not expose public resolution selection.
• For Nano Banana reference-image requests, use nano-banana-edit or nano-banana-pro on this endpoint (/v1/images/generations) with operation: "image-to-image" and image_urls. Do not send Nano Banana reference-image requests to /v1/images/edits.
• Reference images on this endpoint can be supplied as JSON image_url / image_urls, or as a multipart image file. images[] and file_id are not accepted on /v1/images/generations; create /v1/files references only for /v1/images/edits models that document images[].file_id.

For Google image families, prefer aspect_ratio and only send resolution when the model explicitly supports it.

xAI Grok Imagine image models (grok-imagine-image, grok-imagine-image-quality, and legacy grok-imagine-image-pro) support aspect_ratio plus resolution (1k, 2k). grok-imagine-image-pro is retained as a compatibility ID for grok-imagine-image-quality.

Request BodyCopy Anchor Link

Synchronous request timeout: Some image requests return the final image inline and wait for generation to finish. High-resolution or high-quality requests can take close to a minute or longer, so set your HTTP client timeout to at least 120s. If the create response includes status: "pending", task_id, or poll_url, follow the returned poll_url instead.

ResponseCopy Anchor Link

Inline ResponseCopy Anchor Link

Async Task ResponseCopy Anchor Link

Set async: true with gpt-image-2 or official FLUX/BFL image models to create a task instead of waiting for the final image in the create request. The response includes status: "pending", task_id, and poll_url. Poll /v1/tasks/{task_id} until the task reaches completed or failed.

Async image tasks return final image URLs only. If you need raw b64_json image data, use a synchronous request.

Billing may reserve the estimated amount when the task is created. Completed tasks are billed by actual usage, and failed or timed-out tasks are released or refunded.

When you receive status: "pending", use poll_url or GET /v1/tasks/{task_id} to retrieve the result.

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

Choose a ModelCopy Anchor Link

Query GET /v1/models?recommended_for=image or use the Models page for current availability, capabilities, and prices.

Do not hard-code a model as always synchronous or always asynchronous. If the create response returns status: "pending", follow poll_url and poll until completion.

Handling Task-Based ResponsesCopy Anchor Link

For image models, always check whether the response contains 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"]
        poll_url = data.get("poll_url")
        print(f"Image task started: {task_id}")

        # Poll for result
        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:
        # 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}")

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