Sample - OpenAI API
POST/images/edits

Create an image edit

Creates edited or extended images from one or more source images and a text prompt. Send multipart form data with image and prompt, or send JSON with images and prompt when using GPT image models. Configure the model, output format, size, quality, background, and streaming behavior as needed.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

15 body fields

Image editing input supplied as multipart form data or JSON. Multipart requests require image and prompt; JSON requests require images and prompt.

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`.
Default:gpt-image-1.5
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
Controls fidelity to the original input image(s).
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
userstringoptional
A unique identifier representing your end-user, which can help OpenAI monitor and detect abuse.
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
The number of partial images to return during streaming. Must be between 0 and 3 and defaults to 0 when omitted.
Default:0

3 status codes
200Returns the generated image response with its creation timestamp, generated image data, output background, format, size, quality, and applicable token usage. Streaming responses emit partial-image events followed by a final image event.
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.
429Returned when the request rate exceeds the permitted limit; reduce the request rate and increase it gradually.

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
503Returned when the image service or requested model is temporarily unavailable because the 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

prompt and either multipart image or JSON images are required. n must be between 1 and 10, partial_images must be between 0 and 3, and output_format must be png, jpeg, or webp when provided. A 429 is returned when the request rate exceeds the limit, and a 503 is returned when the requested model is temporarily overloaded.