Image generation

TokenLab supports text-to-image, image-to-image, and image editing. Parameters differ by model, so check the selected model’s request fields before sending the request.

Choose an endpoint

What you need	Endpoint	Use when	Not for
Text-to-image	`POST /v1/images/generations`	The user starts with text only	Editing an existing GPT Image file
Image-to-image	`POST /v1/images/generations`	The model accepts `operation: "image-to-image"` and image URLs	Models that require multipart edit input
Image edit	`POST /v1/images/edits`	A supported edit model changes an existing image	Nano Banana-style reference generation
Variation	`POST /v1/images/variations`	An existing integration already uses the variations API	A new reference-image feature
Status	`GET /v1/tasks/{id}`	A create response returns `task_id`, `status: "pending"`, or `poll_url`	The create response already contains final `data[]`

Always send model; image APIs do not choose a default model for you.

Choose a model

Find current image models with:

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

Open the selected model’s details to confirm:

The supported operation, such as text-to-image, image-to-image, or image-edit.
The request endpoint expected by the model.
How to send references: image_url, image_urls, reference_image_urls, multipart image, or JSON images[].
Whether the model accepts size, aspect_ratio, resolution, quality, background, output_format, or response_format.

Model-specific fields

gpt-image-2 style requests use OpenAI-like size, quality, and edit fields. For generation and edits, background accepts auto or opaque; transparent is not supported. Omit optional fields to use automatic defaults.
Gemini and Nano Banana image families usually use aspect_ratio; only send resolution when the model details expose it.
Nano Banana image-to-image belongs on /v1/images/generations with operation: "image-to-image" and reference image URLs.
/v1/images/generations does not accept top-level images[] or file_id; those are edit-flow shapes.
Remote image references must be public http or https URLs. Do not send private network URLs, embedded credentials, URL fragments, or signed URLs that may expire before processing starts.

Text-to-image example

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean product photo of a ceramic coffee cup on a walnut desk",
    "size": "1024x1024",
    "response_format": "url"
  }'

Reference-image example

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "operation": "image-to-image",
    "prompt": "Keep the product shape, change the background to a bright studio setup",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

Get the image

Image responses can be synchronous or asynchronous:

Synchronous responses return final data[] with url or b64_json.
Async responses return id, task_id, status, and usually poll_url.
Use poll_url when it is present. If you need a fixed URL, call GET /v1/tasks/{id}.
Use a synchronous request when you need b64_json; async image results use URLs.

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

Persist the returned image URL, task ID, model, and your own user/job ID. Do not keep polling after a terminal status.

Before launch

Validate user inputs before calling TokenLab: prompt length, image count, URL reachability, and file type.
Set HTTP timeouts high enough for synchronous high-resolution requests. Use async mode where available for long work.
Store request_id, task_id, poll_url, model, endpoint, and the field names sent.
On client timeout, check whether a task was created before retrying the create request.
Use Usage and billing_transaction_id for the final charge.

Common Errors

Symptom	Likely cause	Fix
`400` with `param: "model"`	Missing explicit model	Query `/v1/models?recommended_for=image` and send `model`
Unsupported field	Field is not documented for that model	Remove the field or choose a model/endpoint that documents it
No `b64_json` on async result	Async image tasks return URL-oriented results	Use synchronous mode for base64 output
Reference image rejected	Wrong endpoint or private/expired URL	Match the model’s documented reference shape and use reachable URLs

API Reference

Topic	Reference
Create Image	Create Image
Edit Image	Edit Image
Create Image Variation	Create Image Variation
Get Image Status	Get Image Status
Get Task Status	Get Task Status

Getting Started

Core Guides

Media Guides

Choose an endpoint

Choose a model

Model-specific fields

Text-to-image example

Reference-image example

Get the image

Before launch

Common Errors

API Reference

​Choose an endpoint

​Choose a model

​Model-specific fields

​Text-to-image example

​Reference-image example

​Get the image

​Before launch

​Common Errors

​API Reference

Choose an endpoint

Choose a model

Model-specific fields

Text-to-image example

Reference-image example

Get the image

Before launch

Common Errors

API Reference