TokenLab

Media Guides

Image generation

Generate or edit images and handle finished files or async tasks

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 needEndpointUse whenNot for
Text-to-imagePOST /v1/images/generationsThe user starts with text onlyEditing an existing GPT Image file
Image-to-imagePOST /v1/images/generationsThe model accepts operation: "image-to-image" and image URLsModels that require multipart edit input
Image editPOST /v1/images/editsA supported edit model changes an existing imageNano Banana-style reference generation
VariationPOST /v1/images/variationsAn existing integration already uses the variations APIA new reference-image feature
StatusGET /v1/tasks/{id}A create response returns task_id, status: "pending", or poll_urlThe 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 with this model, 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. On models with resolution tiers, a size of 1K, 2K, or 4K is sent as resolution; a tier that is different from resolution is refused.
  • 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. Send "async": true on a model that supports public async execution to get a task instead of waiting for the image.
  • To check an async task, call GET /v1/tasks/{id} with the returned id or task_id.
  • Use a synchronous request when you need b64_json; async image results use URLs.

Image result URLs are TokenLab media-result URLs that stay valid for 30 days. media_retention.items reports each item's saving status and expires_at; the response can omit media_retention when the saving status is not known in time, and the URL still works. Inline Base64 results are outside this URL-copy retention. Manually saving an image to the Media Library gives it a separate lifecycle. See Data retention.

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: true where the model supports it for long work.
  • Store request_id, task_id, poll_url, model, endpoint, and the field names sent.
  • When an image request returns a task, an Idempotency-Key makes the create request safe to retry: after a client timeout, send the same request with the same key to get that task. For a request that returns the image directly, a retry with the same key can return a task status instead of the image, or 409 with idempotent_response_not_replayable. Without a key, check whether a task was created before you retry.
  • Use Usage and billing_transaction_id for the final charge.

Common Errors

SymptomLikely causeFix
400 with param: "model"Missing explicit modelQuery /v1/models?recommended_for=image and send model
Unsupported fieldField is not documented for that modelRemove the field or choose a model/endpoint that documents it
No b64_json on async resultAsync image tasks return URL-oriented resultsUse synchronous mode for base64 output
Reference image rejectedWrong endpoint or private/expired URLMatch the model's documented reference shape and use reachable URLs

API Reference

TopicReference
Create ImageCreate Image
Edit ImageEdit Image
Create Image VariationCreate Image Variation
Get Image StatusGet Image Status
Get Task StatusGet Task Status

On this page