/v1/schemas/openai/image/images/edits
| field | recorded source |
|---|---|
| schema | Source linked above. upstream-spec Source trace898eefefea6b5dc52da42f5628a64a0ffba65d850282e1cb59ab459f7e356f92{
"fetchedAt": 1793851833,
"extractorVersion": "1",
"verifiedAt": null
} |
Request body
20 properties · 2 required · 6 $defs| property | type | description | constraints |
|---|---|---|---|
| image* | string | string[] | The image(s) to edit. Must be a supported image file or an array of images. | |
| prompt* | string | A text description of the desired image(s). The maximum length is 32000 characters for the GPT image models. | |
| frame_count | frame_count | Number of frames for GIF output. Accepts integers from 2 through 16. Defaults to 9 when omitted. Only supported with output_format=gif. The requested size must satisfy the selected model's GIF size limits. GIF output does not support streaming, partial images,… | 2 ≤ n ≤ 16 |
| frame_duration_ms | frame_duration_ms | Requested delay per GIF frame, in milliseconds. Defaults to 200 when omitted. GIF output rounds to the nearest 10 ms and caps the encoded delay at 655,350 ms per frame. Only supported with output_format=gif. | n ≥ 20 |
| complexity | enum | Computation spent planning the image, independently of rendering quality. Uses the image model's configured default when omitted. For SVG output, controls the reference image, independently of the SVG author's reasoning. | low | medium | high | null |
| mask | string | An additional image whose fully transparent areas (e.g. where alpha is zero) indicate where `image` should be edited. If there are multiple images provided, the mask will be applied on the first image. Must be a valid PNG file, less than 4MB, and have the same… | format: binary |
| markup | string | A transparent PNG overlaid on the first image to guide the edit. Must match that image's dimensions after orientation and contain transparent pixels. Supports GPT Image 2.5. Cannot be combined with mask. | format: binary |
| background | enum | Allows to set transparency for the background of the generated image(s). Must be one of `transparent`, `opaque`, or `auto` (default value). When `auto` is used, the model will automatically determine the best background for the image. `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`. | transparent | opaque | auto · nullable |
| model | string | enum | The GPT image model to use for image editing (`gpt-image-1-mini`, `gpt-image-1.5`, `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`, `gpt-image-2.5-flare-2026-09-08`, `gpt-image-2.6-s… | |
| n | any | The number of images to generate. Must be between 1 and 10. | 1 ≤ n ≤ 10 · default: 1 |
| size | string | enum | The size of the generated images. Defaults to `auto`. 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 a… | |
| response_format | enum | Legacy response format parameter for retired image models. Unsupported for GPT image models, which always return base64-encoded images. | url | b64_json | null · deprecated |
| output_format | enum | The format in which the generated images are returned. This parameter is only supported for the GPT image models. The default value is `png`. | png | jpeg | webp | gif · nullable |
| output_compression | any | The compression level (0-100%) for the generated images. This parameter is only supported for the GPT image models with the `webp` or `jpeg` output formats, and defaults to 100. | default: 100 |
| safety_identifier | any | 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 omi… | length ≤ 128 |
| user | string | 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-… | deprecated |
| input_fidelity | enum | 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.5`; `gpt-image-1-mini` supports only `low`. For `gpt-image-2`, omit this parameter. Defaults to… | high | low · nullable |
| stream | any | Edit the image in streaming mode. Defaults to `false`. See the [Image generation guide](https://developers.openai.com/api/docs/guides/image-generation) for more information. | default: false |
| partial_images | integer | The number of partial images to generate. This parameter is used for streaming responses that return partial images. Value must be between 0 and 3. When set to 0, the response will be a single image sent in one streaming event. | 0 ≤ n ≤ 3 · default: 0 · nullable |
| quality | enum | The quality of the image that will be generated 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`. | low | medium | high | xhigh | max | auto · +1 more · nullable |
Types
6 $defscomplexityenum
Computation spent planning the image, independently of rendering quality. Uses the image model's configured default when omitted. For SVG output, controls the reference image, independently of the SVG author's reasoning.
low | medium | high | null
frame_countany
Number of frames for GIF output. Accepts integers from 2 through 16. Defaults to 9 when omitted. Only supported with output_format=gif. The requested size must satisfy the selected model's GIF size limits. GIF output does not support streaming, partial images,…
2 ≤ n ≤ 16
frame_duration_msany
Requested delay per GIF frame, in milliseconds. Defaults to 200 when omitted. GIF output rounds to the nearest 10 ms and caps the encoded delay at 655,350 ms per frame. Only supported with output_format=gif.
n ≥ 20
InputFidelityenum
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.5`; `gpt-image-1-mini` supports only `low`. For `gpt-image-2`, omit this parameter. Defaults to…
high | low
markupstring
A transparent PNG overlaid on the first image to guide the edit. Must match that image's dimensions after orientation and contain transparent pixels. Supports GPT Image 2.5 and 2.6. Cannot be combined with mask.
format: binary
PartialImagesinteger
The number of partial images to generate. This parameter is used for streaming responses that return partial images. Value must be between 0 and 3. When set to 0, the response will be a single image sent in one streaming event.
0 ≤ n ≤ 3 · default: 0 · nullable
Validate a payload
before you spend tokens$ curl -X POST https://modelschemas.com/v1/validate \
-d '{"provider":"openai","endpointId":"images/edits","payload":{…}}'
→ {"valid": false, "errors": [{"path": "#", "keyword": "required", …}]}