Edit Images

POST /images/edits

Edit Images

cURL

curl --request POST \
  --url https://api.example.com/images/edits

import requests

url = "https://api.example.com/images/edits"

response = requests.post(url)

print(response.text)

const options = {method: 'POST'};

fetch('https://api.example.com/images/edits', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/images/edits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/images/edits"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/images/edits")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/images/edits")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

200

{
  "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.

Show Image object

url · string

The URL of the generated image (for dall-e-2 with response_format=url).

b64_json · string

The base64-encoded JSON of the generated image (for GPT image models or dall-e-2 with response_format=b64_json).

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)