Images
Create an image edit multipart Create an image edit json
Creates an image edit multipart from the supplied request. Creates an image edit json from the supplied request.
Request Body
The multipart request body. The request body.
image
any | string[]
required
The image(s) to edit. Must be a supported image file or an array of images. For the GPT image models (gpt-image-1, 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, and gpt-image-2.5-flare-2026-09-08), 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 as GPT image models.
prompt
string
required
A text description of the desired image(s). The maximum length is 32000 characters for the GPT image models.
mask
OpenAI.CreateImageEditRequest
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.
background
enum
Set the background of the generated image(s). This parameter is only supported for the GPT image models. 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.
model
string | enum
required
The GPT image model to use for image editing (gpt-image-1, 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, or chatgpt-image-latest).
enum
n
integer | null
The number of images to generate. Must be between 1 and 10.
size
string | enum | null
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 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.
enum
response_format
enum
Legacy response format parameter for retired image models. Unsupported for GPT image models, which always return base64-encoded images.
output_format
enum
The format in which the generated images are returned. This parameter is only supported for the GPT image models. Must be one of png, jpeg, or webp. The default value is png.
output_compression
integer | null
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.
safety_identifier
string | null
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.
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.
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 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.
stream
boolean | null
Edit the image in streaming mode. Defaults to false. See the Image generation guide for more information.
partial_images
integer | null
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.
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.
model
string | enum | null
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.
enum
images
OpenAI.ImageRefParam[]
required
Input image references to edit. For GPT image models, you can provide up to 16 images.
mask
object | object
Reference an input image by either URL or uploaded file ID. Provide exactly one of image_url or file_id.
prompt
string
required
A text description of the desired image edit.
n
integer | null
The number of edited images to generate.
quality
enum
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
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 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
string | enum | null
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.
enum
safety_identifier
string | null
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.
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.
output_format
enum
Output image format. Supported for GPT image models.
output_compression
integer | null
Compression level for jpeg or webp output.
moderation
enum
Moderation level for GPT image models.
background
enum
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
boolean | null
Stream partial image results as events.
partial_images
integer | null
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.
Responses
The request has succeeded.
Body
safety_identifier
string | null
The effective safety identifier used for safety monitoring and abuse detection. This is the non-empty safety_identifier from the request, or the deprecated user value when safety_identifier is omitted, null, or empty.
created
integer
required
The Unix timestamp (in seconds) of when the image was created.
data
OpenAI.Image[]
The list of generated images.
background
enum
The background parameter used for the image generation. Either transparent or opaque.
output_format
enum
The output format of the image generation. Either png, webp, or jpeg.
size
string | enum
The image dimensions as a WIDTHxHEIGHT string, for example 1536x864.
enum
quality
enum
The quality of the image generated. One of low, medium, high, xhigh, or max.
usage
OpenAI.ImageGenUsage
For gpt-image-1 only, the token usage information for the image generation.
output_tokens_details
OpenAI.ImageGenOutputTokensDetails
The output token details for the image generation.
input_tokens_details
OpenAI.ImageGenInputUsageDetails
required
The input tokens detailed information for the image generation.
Request
curl -s -D >(grep -i x-request-id >&2) \
-o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \
-X POST "https://api.openai.com/v1/images/edits" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F "model=gpt-image-1.5" \
-F "image[]=@body-lotion.png" \
-F "image[]=@bath-bomb.png" \
-F "image[]=@incense-kit.png" \
-F "image[]=@soap.png" \
-F 'prompt=Create a lovely gift basket with these four items in it'import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
)
for image in client.images.edit(
image=b"Example data",
prompt="A cute baby sea otter wearing a beret",
):
print(image)import fs from "fs";
import OpenAI, { toFile } from "openai";
const client = new OpenAI();
const imageFiles = [
"bath-bomb.png",
"body-lotion.png",
"incense-kit.png",
"soap.png",
];
const images = await Promise.all(
imageFiles.map(async (file) =>
await toFile(fs.createReadStream(file), null, {
type: "image/png",
})
),
);
const rsp = await client.images.edit({
model: "gpt-image-1.5",
image: images,
prompt: "Create a lovely gift basket with these four items in it",
});
// Save the image to a file
const image_base64 = rsp.data[0].b64_json;
const image_bytes = Buffer.from(image_base64, "base64");
fs.writeFileSync("basket.png", image_bytes);import fs from 'fs';
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted
});
const imagesResponse = await client.images.edit({
image: fs.createReadStream('path/to/file'),
prompt: 'A cute baby sea otter wearing a beret',
});
console.log(imagesResponse);package main
import (
"bytes"
"context"
"fmt"
"io"
"github.com/openai/openai-go"
"github.com/openai/openai-go/option"
)
func main() {
client := openai.NewClient(
option.WithAPIKey("My API Key"),
)
imagesResponse, err := client.Images.Edit(context.TODO(), openai.ImageEditParams{
Image: openai.ImageEditParamsImageUnion{
OfFile: io.Reader(bytes.NewBuffer([]byte("Example data"))),
},
Prompt: "A cute baby sea otter wearing a beret",
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v
", imagesResponse)
}package com.openai.example;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.images.ImageEditParams;
import com.openai.models.images.ImagesResponse;
import java.io.ByteArrayInputStream;
import java.io.InputStream;
public final class Main {
private Main() {}
public static void main(String[] args) {
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
ImageEditParams params = ImageEditParams.builder()
.image(new ByteArrayInputStream("Example data".getBytes()))
.prompt("A cute baby sea otter wearing a beret")
.build();
ImagesResponse imagesResponse = client.images().edit(params);
}
}require "openai"
openai = OpenAI::Client.new(api_key: "My API Key")
images_response = openai.images.edit(image: StringIO.new("Example data"), prompt: "A cute baby sea otter wearing a beret")
puts(images_response)Request
curl -s -N -X POST "https://api.openai.com/v1/images/edits" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F "model=gpt-image-1.5" \
-F "image[]=@body-lotion.png" \
-F "image[]=@bath-bomb.png" \
-F "image[]=@incense-kit.png" \
-F "image[]=@soap.png" \
-F 'prompt=Create a lovely gift basket with these four items in it' \
-F "stream=true"import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
)
for image in client.images.edit(
image=b"Example data",
prompt="A cute baby sea otter wearing a beret",
):
print(image)import fs from "fs";
import OpenAI, { toFile } from "openai";
const client = new OpenAI();
const imageFiles = [
"bath-bomb.png",
"body-lotion.png",
"incense-kit.png",
"soap.png",
];
const images = await Promise.all(
imageFiles.map(async (file) =>
await toFile(fs.createReadStream(file), null, {
type: "image/png",
})
),
);
const stream = await client.images.edit({
model: "gpt-image-1.5",
image: images,
prompt: "Create a lovely gift basket with these four items in it",
stream: true,
});
for await (const event of stream) {
console.log(event);
}import fs from 'fs';
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted
});
const imagesResponse = await client.images.edit({
image: fs.createReadStream('path/to/file'),
prompt: 'A cute baby sea otter wearing a beret',
});
console.log(imagesResponse);package main
import (
"bytes"
"context"
"fmt"
"io"
"github.com/openai/openai-go"
"github.com/openai/openai-go/option"
)
func main() {
client := openai.NewClient(
option.WithAPIKey("My API Key"),
)
imagesResponse, err := client.Images.Edit(context.TODO(), openai.ImageEditParams{
Image: openai.ImageEditParamsImageUnion{
OfFile: io.Reader(bytes.NewBuffer([]byte("Example data"))),
},
Prompt: "A cute baby sea otter wearing a beret",
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v
", imagesResponse)
}package com.openai.example;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.images.ImageEditParams;
import com.openai.models.images.ImagesResponse;
import java.io.ByteArrayInputStream;
import java.io.InputStream;
public final class Main {
private Main() {}
public static void main(String[] args) {
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
ImageEditParams params = ImageEditParams.builder()
.image(new ByteArrayInputStream("Example data".getBytes()))
.prompt("A cute baby sea otter wearing a beret")
.build();
ImagesResponse imagesResponse = client.images().edit(params);
}
}require "openai"
openai = OpenAI::Client.new(api_key: "My API Key")
images_response = openai.images.edit(image: StringIO.new("Example data"), prompt: "A cute baby sea otter wearing a beret")
puts(images_response)Response
event: image_edit.partial_image
data: {"type":"image_edit.partial_image","b64_json":"...","partial_image_index":0}
event: image_edit.completed
data: {"type":"image_edit.completed","b64_json":"...","usage":{"total_tokens":100,"input_tokens":50,"output_tokens":50,"input_tokens_details":{"text_tokens":10,"image_tokens":40}}}