Images

Create image

Creates an image given a prompt.

post/v1/images/generations

Request

  • Base URL: https://api.tokenlab.sh
  • URL: https://api.tokenlab.sh/v1/images/generations
  • Auth: HTTP bearer

Headers

X-TokenLab-Delivery-Policy'auto' | 'verified' | 'official'

Per-request Delivery policy. Overrides the API key and Workspace defaults. Auto tries TokenLab Verified first and may switch once to Official only before output, request acceptance, or persistent resource creation.

Request body

promptstring

Image description. Required for every model that takes a prompt; a tool whose contract lists no prompt (background removal, upscaling, vectorizing) is called without one.

modelstring required

Model to use. Send this explicitly; query GET /v1/models?recommended_for=image for current recommendations.

operation'text-to-image' | 'image-to-image' | 'image-edit'

Public image operation family. Reference-image models use image-to-image with image_url, image_urls, or reference_image_urls.

image_urlstring uri

Single reference image URL for compatible image-to-image models.

image_urlsstring[]

Reference image URLs for compatible image-to-image models.

reference_image_urlsstring[]

Alias used by compatible reference-image model families.

mask_urlstring uri

Optional mask URL for compatible image operations.

ninteger

Number of images to generate

sizestring

Image size. Defaults are model-specific. For gpt-image-2, omit this field or use auto for automatic sizing, or send WIDTHxHEIGHT; custom dimensions must both be multiples of 16, longest edge <= 3840px, long/short ratio <= 3:1, and total pixels between 655,360 and 8,294,400. For Google image models with resolution tiers (gemini-3.1-flash-image, gemini-3-pro-image, gemini-3.1-flash-lite-image, gemini-nano-banana-2.1, nano-banana-2, nano-banana-2.1, nano-banana-pro), send an output size from the model's size table or a resolution tier: 1K, 2K, or 4K. TokenLab sends a tier as resolution. A tier that the model does not support, or a tier that is different from resolution, returns 400 invalid_image_size_contract. The recommended form for these models is aspect_ratio with resolution.

qualitystring

Image quality. Defaults and accepted values are model-specific. For gpt-image-2, omit this field or use auto for automatic quality, or send low, medium, or high. Other models may accept different values; check the model details.

style'vivid' | 'natural'

Optional model-specific style selector. Only send when the selected model documents support for this parameter.

expand_promptboolean

Ask compatible models to expand or enhance the prompt.

prompt_extendboolean

For z-image-turbo, enable prompt expansion. Defaults to false. Enabling it uses the model's prompt-expansion price.

negative_promptstring

Content to avoid for compatible image models.

seedinteger

Seed for deterministic-compatible image models.

response_format'url' | 'b64_json'

How the images are returned. Omitted: when the model returns image bytes, each image is in data[].b64_json, and also in data[].url when TokenLab stored it; when the model returns a link, each image is in data[].url. url: only data[].url. b64_json: only data[].b64_json. Links are TokenLab media-result URLs that stay valid for 30 days.

asyncboolean

Return a task before the final image is ready when the selected model supports public async execution.

background'transparent' | 'opaque' | 'auto'

Background handling for compatible image flows. For gpt-image-2 generation and edits, accepted values are auto and opaque; transparent is not supported. Other models may support different values.

output_format'png' | 'jpeg' | 'webp'

Output image format for compatible image models such as gpt-image-2

output_compressioninteger

Output compression level from 0 to 100 for compressed formats

compressioninteger

Alias for output_compression when supported by the selected model

moderation'auto' | 'low'

Moderation strictness for compatible image models such as gpt-image-2

streamboolean

Reserved image streaming flag. The public generation route currently rejects true.

aspect_ratiostring

Aspect-ratio selector for compatible image model families.

resolutionstring

Resolution selector for compatible image model families.

userstring

End-user identifier

Response

Successful response

createdinteger required

Unix timestamp

task_idstring

Task ID when the request runs as a task.

statusstring

Task status when the request runs as a task.

poll_urlstring

URL to poll for the task result.

Example response

{
  "media_retention": {
    "days": 30
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.