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 endpointCopy Anchor Link

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

Choose a modelCopy Anchor Link

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 fieldsCopy Anchor Link

• 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 exampleCopy Anchor Link

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 exampleCopy Anchor Link

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 imageCopy Anchor Link

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.

Eligible generated image HTTP(S) result URLs may be retained as media copies for 30 days. Check media_retention.items for each item's status and expires_at; pending or failed copies are not guaranteed. 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 launchCopy Anchor Link

• 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 ErrorsCopy Anchor Link

API ReferenceCopy Anchor Link