Skip to main content
POST
/
images
/
edits
Edit Images
curl --request POST \
  --url https://api.example.com/images/edits
{
  "created": 123,
  "data": [
    {
      "url": "<string>",
      "b64_json": "<string>"
    }
  ]
}
Creates an edited or extended image given one or more source images and a prompt. This endpoint supports GPT Image models (gpt-image-1.5, gpt-image-1, gpt-image-1-mini, and chatgpt-image-latest) and dall-e-2.

​
Method Signature

client.images.edit(
    image=open("source.png", "rb"),
    prompt="Add sunglasses to the person",
    mask=open("mask.png", "rb"),
    model="gpt-image-1.5",
    size="1024x1024"
)

​
Parameters

​
image
file
required
The image(s) to edit. Must be a supported image file or an array of images.For GPT image models:
  • Each image should be a png, webp, or jpg file less than 50MB
  • You can provide up to 16 images
  • chatgpt-image-latest follows the same input constraints
For dall-e-2:
  • You can only provide one image
  • Must be a square png file less than 4MB
​
prompt
string
required
A text description of the desired image(s). The maximum length is:
  • 32000 characters for GPT image models
  • 1000 characters for dall-e-2
​
mask
file
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 dimensions as image.
​
model
string
The model to use for image generation. Options:
  • gpt-image-1.5 (default)
  • gpt-image-1
  • gpt-image-1-mini
  • chatgpt-image-latest
  • dall-e-2
​
n
integer
The number of images to generate. Must be between 1 and 10.
​
size
string
The size of the generated images:
  • GPT image models: 1024x1024, 1536x1024 (landscape), 1024x1536 (portrait), or auto (default)
  • dall-e-2: 256x256, 512x512, or 1024x1024
​
response_format
string
The format in which the generated images are returned. Must be one of url or b64_json.Only supported for dall-e-2 (default is url). GPT image models always return base64-encoded images.
​
quality
string
The quality of the image that will be generated for GPT image models:
  • auto (default)
  • standard
  • low
  • medium
  • high
​
background
string
Allows to set transparency for the background of the generated image(s). Only supported for GPT image models:
  • transparent
  • opaque
  • auto (default) - model automatically determines the best background
If transparent, the output format needs to support transparency (png or webp).
​
input_fidelity
string
Control how much effort the model will exert to match the style and features, especially facial features, of input images. Only supported for gpt-image-1 and gpt-image-1.5 and later models, unsupported for gpt-image-1-mini:
  • low (default)
  • high
​
output_format
string
The format in which the generated images are returned. Only supported for GPT image models:
  • png (default)
  • jpeg
  • webp
​
output_compression
integer
The compression level (0-100%) for the generated images. Only supported for GPT image models with webp or jpeg output formats. Defaults to 100.
​
stream
boolean
Edit the image in streaming mode. Defaults to false. See the Image generation guide for more information.
​
partial_images
integer
The number of partial images to generate. Used for streaming responses. Value must be between 0 and 3. When set to 0, the response will be a single image sent in one streaming event.
​
user
string
A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

​
Returns

Returns an ImagesResponse object containing the edited images.
​
created
integer
The Unix timestamp (in seconds) of when the image was created.
​
data
array
The list of generated images.

​
Examples

​
Edit with mask (DALL-E 2)

from openai import OpenAI
client = OpenAI()

response = client.images.edit(
    model="dall-e-2",
    image=open("sunlit_lounge.png", "rb"),
    mask=open("mask.png", "rb"),
    prompt="A sunlit indoor lounge area with a pool containing a flamingo",
    n=1,
    size="1024x1024"
)

image_url = response.data[0].url
print(f"Edited image URL: {image_url}")

​
Edit without mask (GPT Image model)

import base64
from openai import OpenAI

client = OpenAI()

response = client.images.edit(
    model="gpt-image-1.5",
    image=open("original.png", "rb"),
    prompt="Make the image look like it was taken at sunset",
    quality="high",
    size="1024x1024"
)

# GPT image models always return base64
image_data = base64.b64decode(response.data[0].b64_json)
with open("edited.png", "wb") as f:
    f.write(image_data)

​
Edit multiple images

from openai import OpenAI
client = OpenAI()

response = client.images.edit(
    model="gpt-image-1",
    image=[
        open("image1.png", "rb"),
        open("image2.png", "rb"),
        open("image3.png", "rb")
    ],
    prompt="Apply a vintage filter to these images",
    input_fidelity="high"
)

import base64
for i, image in enumerate(response.data):
    image_data = base64.b64decode(image.b64_json)
    with open(f"edited_{i}.png", "wb") as f:
        f.write(image_data)

​
Edit with transparent background

import base64
from openai import OpenAI

client = OpenAI()

response = client.images.edit(
    model="gpt-image-1.5",
    image=open("product.png", "rb"),
    prompt="Remove the background and keep only the product",
    background="transparent",
    output_format="png"
)

image_data = base64.b64decode(response.data[0].b64_json)
with open("product_no_bg.png", "wb") as f:
    f.write(image_data)

Build docs developers (and LLMs) love

Get started for freeTalk to us