Images
Edit Image
Edit an image given a prompt and source image
Overview
Creates an edited or extended image given an original image and a prompt.
This endpoint supports both:
- the OpenAI-compatible
multipart/form-dataupload flow documented below - JSON requests that provide
image_url,image_urls, or officialimagesreferences for supported image-to-image families
gpt-image-2 is supported here. It accepts multipart image uploads, JSON image_url / image_urls, and official images[] references (image_url or file_id), with up to 16 source images. Create file_id values through /v1/files first. Set async: true to return a task first; every model that lists async among its supported parameters, such as gpt-image-2 and the FLUX edit models, uses the same task polling flow.
gpt-image-2 edits do not accept resolution; use size for output dimensions. background accepts auto or opaque; transparent is not supported. For multi-image or high-latency edits, prefer async: true and poll the returned task.
Nano Banana reference-image requests (nano-banana-2, nano-banana-2.1, nano-banana-2-lite, and nano-banana-pro) are exposed on /v1/images/generations with operation: "image-to-image" and image_urls, not on this /v1/images/edits endpoint. Image-edit requests for nano-banana-2, nano-banana-2.1, nano-banana-2-lite, and nano-banana-pro also use /v1/images/generations, with operation: "image-edit".
gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3.1-flash-lite-image, and gemini-3-pro-image use this endpoint for image-edit. Their image-to-image requests use /v1/images/generations with operation: "image-to-image".
xAI Grok Imagine image edit models accept a limited number of source images: grok-imagine-image-2.0 accepts at most 5, and grok-imagine-image accepts at most 3. Requests with more source images than the model accepts fail input validation with 400 too_many_images. Their image-to-image requests also use this endpoint.
Each model's details (GET /v1/models/{model}, see Get Model) give the endpoint for each operation in tokenlab.request_format_summary.request_endpoint_by_operation, and the accepted fields and limits in tokenlab.request_format_details.operation_constraints. An operation sent to the wrong endpoint returns 400 unsupported_endpoint.
input_fidelity is not part of the current TokenLab supported fields for gpt-image-2; omit it or the request returns 400 unsupported_parameter.
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 least 120s. If the create response includes status: "pending", task_id, or poll_url, poll GET /v1/tasks/{task_id} instead.
Remote image URLs: when multipart input is needed, TokenLab fetches JSON image_url, image_urls, or images[].image_url and sends the bytes as multipart image parts. URLs must be public http/https, without embedded credentials or fragments, and must not resolve to localhost, private, or reserved IP ranges; each redirect is checked again. The fetched payload must be a real PNG, JPEG, or WebP image. Limits are 50 MiB per image, 200 MiB total for URL-fetched images in one request, 30s fetch timeout, and up to 3 redirects.
For JSON requests, provide exactly one of image_url, image_urls, or images. Each images[] object must contain exactly one of image_url or file_id. The 200 MiB aggregate limit includes all source images and the mask.
Multipart source images. Repeat image to provide multiple GPT Image sources. Files must be PNG, JPEG, or WebP, up to 16 source images and 50 MiB each. xAI Grok Imagine edit models use the same input fields but cap source images: at most 5 for grok-imagine-image-2.0 and at most 3 for the other xAI edit models.
A text description of the desired edit, up to 32,000 characters. Required for every model whose details list prompt. Tools without a prompt, such as stability-upscale-fast, are called without one.
An additional image whose fully transparent areas indicate where the image should be edited. Must be a valid PNG file, less than 50 MiB, and have the same dimensions as image.
For JSON requests, mask may also be an object with exactly one of image_url or file_id; file_id values must come from /v1/files and remain bound to the same image-edit configuration.
The model to use for image edits. Use gpt-image-2 for GPT Image edits, or another current image-edit model returned by GET /v1/models?recommended_for=image.
1Number of images to generate (1-10, model dependent).
File format of the edited image: png, jpeg, or webp. gpt-image-2.6-flare and gpt-image-2.6-sunburst also accept gif to animate the source image; SVG output is not available for edits. A GIF request does not accept mask, partial_images, or output_compression.
9Number of GIF frames, from 2 to 16. Only with output_format: "gif".
200Time of each GIF frame in milliseconds, from 20 to 2000. Only with output_format: "gif".
The size of the generated image. For gpt-image-2, use auto or WIDTHxHEIGHT; dimensions must be multiples of 16, longest edge at most 3840px, long/short ratio at most 3:1, and total pixels between 655,360 and 8,294,400.
For gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image, and gemini-3.1-flash-lite-image, size accepts 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 with code invalid_image_size_contract. The recommended form is aspect_ratio with resolution.
How the images are returned: url or b64_json.
- Omitted: when the model returns image bytes, each image is in
data[].b64_json, and also indata[].urlwhen TokenLab stored it. When the model returns a link, each image is indata[].url. url: each image is only indata[].url.b64_json: each image is only indata[].b64_jsonas Base64 data.
Links are TokenLab media-result URLs. They stay valid for 30 days. See Data retention.
falseSet to true to return a task before the final image is ready. Only models that list async among their supported parameters accept it, for example gpt-image-2; for any other model the request returns 400 unsupported_async_mode. Completed async edits return URLs regardless of the requested response_format; use synchronous requests when you need b64_json.
A unique identifier representing your end-user for abuse monitoring.
Response
Unix timestamp of when the images were created.
Array of generated images.
Each object contains:
url(string): TokenLab media-result URL of the edited image, valid for 30 days. Not present whenresponse_formatisb64_json. Whenresponse_formatis omitted, it is missing if TokenLab could not store the image.b64_json(string): Base64 image data. Present whenresponse_formatisb64_json, or when it is omitted and the model returns image bytes.
Token counts (input_tokens, output_tokens, total_tokens, and their details) for token-priced models such as gpt-image-2, when available.
Async Task Response
Set async: true on a model that supports it to create a task instead of waiting for the edited image in the request. The response includes status: "pending", task_id, and poll_url. Poll /v1/tasks/{task_id} until the task reaches completed or failed.
Async edit 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.
Request
curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
-H "Authorization: Bearer sk-your-api-key" \
-F "model=gpt-image-2" \
-F "image=@sunlit_lounge.png" \
-F "mask=@mask.png" \
-F "prompt=A sunlit indoor lounge area with a pool" \
-F "n=1" \
-F "size=1024x1024"Response
{
"created": 1706000000,
"data": [
{
"url": "https://..."
}
]
}Notes
Remote image fetch failures are returned as input errors before generation begins. Unreachable URLs, timeouts, 403/404 responses, private/internal hosts, credentials or fragments in the URL, non-image content, unsupported formats, and size-limit violations return 400 or 413 and identify the image_url / image_urls[n] input. The code is invalid_image_url, unsupported_image_content_type, too_many_images, or, with 413, image_too_large or image_input_too_large. For private or header-protected assets, upload multipart image files directly or create /v1/files references.
Send an Idempotency-Key header to retry a request safely after a timeout; see Retry safely with an idempotency key.
Hy Image 3.5 Preview edits a reference image from a written instruction. It takes size 1024x1024 and n 1 only:
{
"model": "hy-image-v3.5-preview",
"prompt": "Change the table to pale blue",
"image_url": "https://example.com/reference.png",
"size": "1024x1024",
"n": 1,
"response_format": "url"
}Authorization
BearerAuth API Key authentication. Create or manage API keys in Dashboard > API > API Keys.
In: header
Headers
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.
Value in
- "auto"
- "verified"
- "official"
Optional key that makes an image request safe to retry if the request created a task. Send a new unique value, such as a UUID, for each request. A retry with the same key and the same body then returns that task and does not create, dispatch, or charge a second 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. A different body with a key that was already accepted is rejected; the status code and error code for that case are not guaranteed. A key longer than 255 characters is ignored, and the request then has no idempotency protection. See Retry safely with an idempotency key.
1 <= length <= 255Response
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json