OpenAI API (unofficial showcase)
POST/images/edits

Create an image edit

Creates an edited image from one or more source images and a text prompt. Send multipart form data with uploaded image files, or JSON with image references; use mask to limit edits to designated areas. You can choose the output format, size, and quality, and optionally stream partial image results.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

16 body fields

Image edit request using multipart form data with uploaded images or JSON with image references. Supply the fields required for the selected request format.

modelstringoptional
The GPT image model to use for image editing, including `gpt-image-2`, its dated snapshot `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`. Defaults to `gpt-image-2.5-sunburst`.
Default:gpt-image-2.5-sunburst
imagesarray<object>required
Input image references to edit. For GPT image models, you can provide up to 16 images.
maskobjectoptional
Reference an input image by either URL or uploaded file ID. Provide exactly one of `image_url` or `file_id`.
promptstringrequired
A text description of the desired image edit.
nintegeroptional
The number of edited images to generate.
Default:1
qualitystringoptional
Output quality for GPT image models. The GPT image models support `low`, `medium`, and `high`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. Defaults to `auto`.
Allowed:lowmediumhighxhighmaxautoDefault:auto
input_fidelitystringoptional
Control how much effort the model will exert to match the style and features, especially facial features, of input images. Supports `high` and `low` on `gpt-image-1` and `gpt-image-1.5`; `gpt-image-1-mini` supports only `low`. For `gpt-image-2`, omit this parameter. Defaults to `low` on supported models.
Allowed:highlow
sizestringoptional
The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing.
Default:auto
safety_identifierstringoptional
A stable identifier for an end user in your organization, used for safety monitoring and abuse detection. Hash a username or email address to avoid sending identifying information. A non-empty value takes precedence over the deprecated `user` parameter. If omitted, null, or empty, the API uses `user` when available. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).
userstringdeprecatedoptional
Deprecated: use `safety_identifier` instead. This parameter remains accepted for backward compatibility and is used when `safety_identifier` is omitted, null, or empty. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).
output_formatstringoptional
Output image format. Supported for GPT image models.
Allowed:pngjpegwebpDefault:png
output_compressionintegeroptional
Compression level for `jpeg` or `webp` output.
moderationstringoptional
Moderation level for GPT image models.
Allowed:lowautoDefault:auto
backgroundstringoptional
Set the background of the generated image output. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, support `opaque` and `transparent` backgrounds. Transparent backgrounds are available for supported GPT Image models. For `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the output format to `png` or `webp`.
Allowed:transparentopaqueautoDefault:auto
streambooleanoptional
Stream partial image results as events.
Default:false
partial_imagesintegeroptional
Number of partial images to return during streaming. Must be between 0 and 3; defaults to 0 when omitted.
Default:0

7 status codes
200Returns generated image data, including the creation time and, when available, encoded image content or a URL, revised prompt, output settings, and usage details. Streaming responses emit partial-image events and a final-image event.
safety_identifierstringoptional
The effective safety identifier used for safety monitoring and abuse detection. This is the non-empty `safety_identifier` from the request, or the deprecated `user` value when `safety_identifier` is omitted, null, or empty.
createdintegerrequired
The Unix timestamp (in seconds) of when the image was created.
dataarray<object>optional
The list of generated images.
backgroundstringoptional
The background parameter used for the image generation. Either `transparent` or `opaque`.
Allowed:transparentopaque
output_formatstringoptional
The output format of the image generation. Either `png`, `webp`, or `jpeg`.
Allowed:pngwebpjpeg
sizestringoptional
The image dimensions as a `WIDTHxHEIGHT` string, for example `1536x864`.
qualitystringoptional
The quality of the image generated. One of `low`, `medium`, `high`, `xhigh`, or `max`.
Allowed:lowmediumhighxhighmax
usageobjectoptional
For `gpt-image-1` only, the token usage information for the image generation.
400Returned when the image request, parameters, or input are invalid.
errorobjectrequired
403Returned when the project does not have access to the requested model.
errorobjectrequired
410Returned when the requested DALL-E image endpoint is unavailable because it has been retired.
errorobjectrequired
429Returned when the request is rejected because a rate limit was exceeded.

One documented failure

  • slow_down

    Your request rate increased too quickly. Please reduce the request rate and gradually increase it again.

    Traffic increased too quickly

errorobjectrequired
500Returned when the image could not be generated or processed.
errorobjectrequired
503Returned when the service is temporarily unavailable or the requested model is overloaded.

One documented failure

  • server_is_overloaded

    The model is temporarily overloaded. Please retry your request after a brief delay.

    The requested model is temporarily overloaded

errorobjectrequired

Error handling

A 400 is returned when the image request, parameters, or input are invalid; a 403 is returned when the project cannot access the requested model; a 410 is returned when you request the retired DALL-E image endpoint. A 429 is returned when a rate limit is exceeded, a 500 when the image cannot be generated or processed, and a 503 when the service or requested model is temporarily unavailable. For multipart requests, provide image, prompt, and model; for JSON requests, provide images and prompt, and use exactly one of image_url or file_id in each image reference.