curl -X POST 'https://api.openai.com/v1/images/edits' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "images": [
    {
      "image_url": "https://example.com/source-image.png",
      "file_id": "file-abc123"
    }
  ],
  "prompt": "Add a watercolor effect and keep the subject centered"
}'

# POST /images/edits (OpenAI API)
Base URL: https://api.openai.com/v1
Auth: Authorization; OpenAI API key; required.
Request formats: application/json, multipart/form-data.
Last verified: 2026-10-20

> Create image edit

## Critical Gotchas
* The Responses API is the primary interface for new text and tool workflows; Chat Completions remains a separate compatibility API.
* Audio transcription uploads use multipart form data rather than a JSON request body.

## cURL
curl -X POST 'https://api.openai.com/v1/images/edits' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "images": [
    {
      "image_url": "https://example.com/source-image.png",
      "file_id": "file-abc123"
    }
  ],
  "prompt": "Add a watercolor effect and keep the subject centered"
}'

## Parameters
| Name | In | Type | Required | Description |
| :--- | :--- | :--- | :--- | :--- |
| images | body | object[] | Yes | Input image references to edit. For GPT image models, you can provide up to 1... |
| prompt | body | string | Yes | A text description of the desired image edit. |
| model | body | string | No | The GPT image model to use for image editing, including `gpt-image-2`, its da... |
| mask | body | object | No | Reference an input image by either URL or uploaded file ID. Provide exactly o... |
| n | body | integer | No | The number of edited images to generate. |
| quality | body | string | No | Output quality for GPT image models. The GPT image models support `low`, `med... |
| input_fidelity | body | string | No | Control how much effort the model will exert to match the style and features,... |
| size | body | string | No | The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`... |
Other params: safety_identifier, user, output_format, output_compression, moderation, background, stream, partial_images

## Response example
{"safety_identifier":"string","created":0}

---
Need an API key? Get one at https://platform.openai.com/api-keys

POST

POST /images/edits — OpenAI API

OpenAI API key (required); https://api.openai.com/v1

OpenAI API

Create image edit

Base URL: https://api.openai.com/v1
Auth: Authorization: Bearer <OPENAI_API_KEY>
Last verified: 2026-10-20 · upstream hash matched

Actions Try in browser→

Agents: curl -H "Accept: text/markdown" this URL
→ 418 tokens · Vary: Accept

Critical gotchas

The Responses API is the primary interface for new text and tool workflows; Chat Completions remains a separate compatibility API.

Audio transcription uploads use multipart form data rather than a JSON request body.

cURL

curl -X POST 'https://api.openai.com/v1/images/edits' \  -H "Authorization: Bearer $OPENAI_API_KEY" \  -H 'Content-Type: application/json' \  -d '{  "images": [    {      "image_url": "https://example.com/source-image.png",      "file_id": "file-abc123"    }  ],  "prompt": "Add a watercolor effect and keep the subject centered"}'

Parameters

Name	In	Type	Required	Description
model	body	string	No	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`.
images	body	object[]	Yes	Input image references to edit. For GPT image models, you can provide up to 16 images.
mask	body	object	No	Reference an input image by either URL or uploaded file ID. Provide exactly one of `image_url` or `file_id`.
prompt	body	string	Yes	A text description of the desired image edit.
n	body	integer	No	The number of edited images to generate.
quality	body	string	No	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`.
input_fidelity	body	string	No	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.
size	body	string	No	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.
safety_identifier	body	string	No	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).
user	body	string	No	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_format	body	string	No	Output image format. Supported for GPT image models.
output_compression	body	integer	No	Compression level for `jpeg` or `webp` output.
moderation	body	string	No	Moderation level for GPT image models.
background	body	string	No	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`.
stream	body	boolean	No	Stream partial image results as events.
partial_images	body	integer	No	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. Note that the final image may be sent before the full number of partial images are generated if the full image is generated more quickly.

Response 200 OK

{
  "safety_identifier": "string",
  "created": 0,
  "data": [
    {
      "b64_json": "string",
      "url": "https://example.com",
      "revised_prompt": "string"
    }
  ],
  "background": "transparent",
  "output_format": "png",
  "size": "string",
  "quality": "low",
  "usage": {
    "input_tokens": 0,
    "total_tokens": 0,
    "output_tokens": 0,
    "output_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 0
    },
    "input_tokens_details": {
      "text_tokens": 0,
      "image_tokens": 0
    }
  }
}

Get a free OpenAI API key → sponsored

Affiliate link - we may earn a commission, at no extra cost to you.