Overview
For coding agents, discover the current recommended image shortlist first withGET /v1/models?recommended_for=image, then send the selected model explicitly to this endpoint.
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. 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 notes
Google Gemini image-family models do not share the same selector contract:gemini-3.1-flash-image,gemini-3-pro-image, andnano-banana-prosupportaspect_ratioplusresolution(1k,2k,4k) for their public text-to-image and image-edit/image-to-image operations.nano-banana-2supportsaspect_ratioplusresolution(1k,2k,4k) for text-to-image generation only in the current TokenLab request format.gemini-2.5-flash-image,nano-banana, andnano-banana-editsupportaspect_ratiobut do not expose publicresolutionselection.- For Nano Banana reference-image requests, use
nano-banana-editornano-banana-proon this endpoint (/v1/images/generations) withoperation: "image-to-image"andimage_urls. Do not send Nano Banana reference-image requests to/v1/images/edits. - For Nano Banana image-to-image requests,
nano-banana-promay includeresolution(1k,2k,4k);nano-banana-editmust omit it.nano-bananaandnano-banana-2are text-to-image models in the current model details. - Reference images on this endpoint can be supplied as JSON
image_url/image_urls, or as a multipartimagefile.images[]andfile_idare not accepted on/v1/images/generations; create/v1/filesreferences only for/v1/images/editsmodels that documentimages[].file_id.
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 Body
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 least120s. If the create response includes status: "pending", task_id, or poll_url, follow the returned poll_url instead.
Model to use (for example,
gpt-image-2, flux-pro, qwen-image-plus, or nano-banana-pro). Query GET /v1/models?recommended_for=image for the current recommended list.Text description of the desired image.
Public HTTPS reference image URL for image-to-image generation. For Nano Banana reference-image requests, set
operation to image-to-image; nano-banana-pro may include resolution, while nano-banana-edit should omit it.Public HTTPS reference image URLs. Use this for one or more reference images in JSON requests.
file_id and images[] are not supported on this endpoint.Additional model-specific reference image URLs for providers that distinguish primary input images from references.
Multipart reference image file for image-to-image generation. Use this when the source image is private or header-protected. This is different from a /v1/files
file_id, which is not accepted on this endpoint.Number of images to generate (1-10, model dependent).
Image size. Use this for OpenAI-style image families and other models that accept exact pixel sizes.For
gpt-image-2, size accepts auto or WIDTHxHEIGHT. Custom dimensions must both be multiples of 16, the longest edge must be at most 3840px, the long/short ratio must be at most 3:1, and total pixels must be between 655,360 and 8,294,400. aspect_ratio and resolution are not part of the current TokenLab model details for gpt-image-2.For Google Gemini image families, size is treated as a compatibility alias that maps onto the model’s public aspect_ratio and, where supported, resolution contract. Prefer sending aspect_ratio directly for those models.Model-dependent aspect ratio selector.Common Google image-family values include
1:1, 16:9, 9:16, 3:2, and 2:3.Model-dependent output resolution selector.Supported on
gemini-3.1-flash-image and gemini-3-pro-image for text-to-image and image-edit, on nano-banana-pro for text-to-image and image-to-image, and on nano-banana-2 for text-to-image only. Typical values are 1k, 2k, and 4k. Do not send this parameter to ratio-only Gemini image families unless the model explicitly documents it. For xAI Grok Imagine image models, use 1k or 2k.Image quality. GPT Image models such as
gpt-image-2 use auto, low, medium, or high. Other image families may use provider-specific values; check the selected model metadata before sending non-default values.Response format:
url or b64_json. The default is url.For Azure Official or Azure-compatible gpt-image-2 requests, TokenLab receives image data as b64_json. For url requests, TokenLab uploads every image to the CDN and returns data[].url. If CDN storage is unavailable or upload fails, the request fails instead of being converted to a Base64 response. For b64_json, the raw Base64 is returned.Set to
true with gpt-image-2 or official FLUX/BFL image models to create a task first. Completed async image tasks return URLs regardless of the requested response_format; use synchronous requests when you need b64_json.Optional style selector. Only send this when the selected model explicitly documents it; omit it for
gpt-image-2 unless the model metadata says otherwise.A unique identifier for the end-user.
Response
Inline Response
Unix timestamp of creation.
Array of generated images.Each object contains:
url(string): URL of the generated imageb64_json(string): Base64-encoded image (if requested)revised_prompt(string): Optional prompt revision, when the selected model returns one
Async Task Response
Setasync: 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.
Unix timestamp of creation.
Unique task identifier for polling.
Initial status:
pending.Relative URL to poll for results, for example
/v1/tasks/{id}.Empty while the task is pending. Completed image tasks return generated image URLs in
data[].url.status: "pending", use poll_url or GET /v1/tasks/{task_id} to retrieve the result.
Available Models
These are current example models, not a fixed catalog. QueryGET /v1/models?recommended_for=image or the Models page for the latest availability and pricing.
| Model | Type | Features |
|---|---|---|
gpt-image-2 | Inline or task-based | Token-priced GPT Image model, flexible sizes |
flux-pro | Often task-based | Photorealistic, high quality |
qwen-image-plus | Often task-based | Strong text rendering and prompt following |
nano-banana-pro | Often task-based | Reference-image workflows and high-resolution output |
grok-imagine-image | Often task-based | xAI image generation with aspect ratio and resolution selection |
ideogram-v3 | Often task-based | Strong text rendering |
status: "pending", follow poll_url and poll until completion.
Handling Task-Based Responses
For image models, always check whether the response containsstatus: "pending":