--- title: "Edit image" method: POST path: "/v1/images/edits" tags: ["Images"] --- # Edit image `POST /v1/images/edits` ## Request - Base URL: `https://api.tokenlab.sh` - URL: `https://api.tokenlab.sh/v1/images/edits` - Auth: HTTP bearer Edits an image using multipart image uploads, JSON image URLs, or the official JSON images array for supported GPT Image models. ## Headers - `X-TokenLab-Delivery-Policy` 'auto' | 'verified' | 'official' ## Request body - union - object - `model` string, required: Model to use for image edits. Send this explicitly. - `prompt` string, required - `image_url` string, uri, required: Single source image URL. Kept for TokenLab compatibility; use images for the official JSON shape. - `n` integer - `quality` string - `size` string - `aspect_ratio` string - `resolution` string - `response_format` string - `background` 'transparent' | 'opaque' | 'auto' - `output_format` 'png' | 'jpeg' | 'webp' - `output_compression` integer - `compression` integer - `moderation` 'auto' | 'low' - `async` boolean: Return a task before the edited image is ready for models that support public async execution. - `stream` boolean: Reserved image streaming flag. The public edit route currently rejects true. - `user` string - `image_urls` string[]: Multiple source image URLs. GPT Image edits accept up to 16 source images; xAI Grok Imagine Image 2.0 edits accept at most 5 source images; the other xAI Grok Imagine edit models accept at most 3. - `images` union[]: Official JSON image references for image edits. Provide exactly one of image_url or file_id for each item. GPT Image edits accept up to 16 source images; xAI Grok Imagine Image 2.0 edits accept at most 5 source images; the other xAI Grok Imagine edit models accept at most 3. - union - object - `image_url` string, uri, required - `file_id` string: A file id returned by TokenLab /v1/files and bound to the same image-edit configuration. - object - `image_url` string, uri - `file_id` string, required: A file id returned by TokenLab /v1/files and bound to the same image-edit configuration. - `mask` union: Optional JSON mask reference for image edits. Provide exactly one of image_url or file_id. Multipart requests can also send mask as a file part. - object - `image_url` string, uri, required: Source mask image URL. Public http/https URLs and compatible data URLs are supported by the runtime validation path. - `file_id` string: A file id returned by TokenLab /v1/files and bound to the same image-edit configuration. - object - `image_url` string, uri: Source mask image URL. Public http/https URLs and compatible data URLs are supported by the runtime validation path. - `file_id` string, required: A file id returned by TokenLab /v1/files and bound to the same image-edit configuration. - object - `model` string, required: Model to use for image edits. Send this explicitly. - `prompt` string, required - `image_url` string, uri: Single source image URL. Kept for TokenLab compatibility; use images for the official JSON shape. - `n` integer - `quality` string - `size` string - `aspect_ratio` string - `resolution` string - `response_format` string - `background` 'transparent' | 'opaque' | 'auto' - `output_format` 'png' | 'jpeg' | 'webp' - `output_compression` integer - `compression` integer - `moderation` 'auto' | 'low' - `async` boolean: Return a task before the edited image is ready for models that support public async execution. - `stream` boolean: Reserved image streaming flag. The public edit route currently rejects true. - `user` string - `image_urls` string[], required: Multiple source image URLs. GPT Image edits accept up to 16 source images; xAI Grok Imagine Image 2.0 edits accept at most 5 source images; the other xAI Grok Imagine edit models accept at most 3. - `images` union[]: Official JSON image references for image edits. Provide exactly one of image_url or file_id for each item. GPT Image edits accept up to 16 source images; xAI Grok Imagine Image 2.0 edits accept at most 5 source images; the other xAI Grok Imagine edit models accept at most 3. - union - object - `image_url` string, uri, required - `file_id` string: A file id returned by TokenLab /v1/files and bound to the same image-edit configuration. - object - `image_url` string, uri - `file_id` string, required: A file id returned by TokenLab /v1/files and bound to the same image-edit configuration. - `mask` union: Optional JSON mask reference for image edits. Provide exactly one of image_url or file_id. Multipart requests can also send mask as a file part. - object - `image_url` string, uri, required: Source mask image URL. Public http/https URLs and compatible data URLs are supported by the runtime validation path. - `file_id` string: A file id returned by TokenLab /v1/files and bound to the same image-edit configuration. - object - `image_url` string, uri: Source mask image URL. Public http/https URLs and compatible data URLs are supported by the runtime validation path. - `file_id` string, required: A file id returned by TokenLab /v1/files and bound to the same image-edit configuration. - object - `model` string, required: Model to use for image edits. Send this explicitly. - `prompt` string, required - `image_url` string, uri: Single source image URL. Kept for TokenLab compatibility; use images for the official JSON shape. - `n` integer - `quality` string - `size` string - `aspect_ratio` string - `resolution` string - `response_format` string - `background` 'transparent' | 'opaque' | 'auto' - `output_format` 'png' | 'jpeg' | 'webp' - `output_compression` integer - `compression` integer - `moderation` 'auto' | 'low' - `async` boolean: Return a task before the edited image is ready for models that support public async execution. - `stream` boolean: Reserved image streaming flag. The public edit route currently rejects true. - `user` string - `image_urls` string[]: Multiple source image URLs. GPT Image edits accept up to 16 source images; xAI Grok Imagine Image 2.0 edits accept at most 5 source images; the other xAI Grok Imagine edit models accept at most 3. - `images` union[], required: Official JSON image references for image edits. Provide exactly one of image_url or file_id for each item. GPT Image edits accept up to 16 source images; xAI Grok Imagine Image 2.0 edits accept at most 5 source images; the other xAI Grok Imagine edit models accept at most 3. - union - object - `image_url` string, uri, required - `file_id` string: A file id returned by TokenLab /v1/files and bound to the same image-edit configuration. - object - `image_url` string, uri - `file_id` string, required: A file id returned by TokenLab /v1/files and bound to the same image-edit configuration. - `mask` union: Optional JSON mask reference for image edits. Provide exactly one of image_url or file_id. Multipart requests can also send mask as a file part. - object - `image_url` string, uri, required: Source mask image URL. Public http/https URLs and compatible data URLs are supported by the runtime validation path. - `file_id` string: A file id returned by TokenLab /v1/files and bound to the same image-edit configuration. - object - `image_url` string, uri: Source mask image URL. Public http/https URLs and compatible data URLs are supported by the runtime validation path. - `file_id` string, required: A file id returned by TokenLab /v1/files and bound to the same image-edit configuration. ## Response `200` Edited image response - ImageGenerationResponse - `created` integer, required: Unix timestamp - `data` object[], required - `url` string: Image URL - `b64_json` string: Base64 encoded image - `revised_prompt` string: Revised prompt returned by models that rewrite or enhance the submitted prompt. - `task_id` string: Task ID when the request runs as a task. - `status` string: Task status when the request runs as a task. - `poll_url` string: URL to poll for the task result. - `error` union: Why the task failed: a string, or an object with `message` and, when known, `type`, `code`, `param` and `retryable`. - string - object - `message` string, required - `type` string - `code` string - `param` string - `retryable` boolean - `error_details` AsyncTaskErrorDetails: Why a task failed. A status read returns HTTP 200 even for a failed task; `status` here is the status of the failure itself. - `projection_version` integer: `2` means `message` is the final reason for the failure. - `status` integer, required - `message` string, required - `type` string, required - `code` string, required - `param` string: The request field at fault, omitted when no specific field is known. - `retryable` boolean, required - `upstream` AsyncTaskUpstreamError: The upstream service's own error, present only for a task that ran on an Official route. Its `code` values are defined by the upstream service and may change; branch on `error_details.code` and `error_details.type`. - `source` string: Upstream service name, when known. - `code` string - `message` string, required - `param` string - `media_retention` MediaRetention: Saving status of the media results in this response. Present when the status is known within the response time limit; when it is absent, the media URLs still work. - `days` integer, required: Days a media-result URL stays valid after the result is first recorded. - `items` object[], required - `url` string, uri, required - `kind` 'image' | 'video' | 'audio' | '3d', required - `content_type` string - `status` 'saving' | 'saved' | 'failed' | 'expired', required - `expires_at` string, date-time, required ## Other responses - `400`: Bad Request - Invalid input - `401`: Unauthorized - Invalid or missing API key - `413`: Bad Request - Invalid input - `500`: Internal Server Error - `503`: The requested Delivery tier is temporarily unavailable. --- [API](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway.md) · [All operations](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/revisions/3208bfbcda22?raw)