Skip to main content

OpenAI GPT Image 2.5 – editing

Prompt-driven editing that keeps the aspect ratio of the images you send, with five quality tiers and two selectable models.
GPT Image 2.5 Edit is an image editing API that modifies one or more images you supply according to a text instruction. It is the reference-image counterpart of GPT Image 2.5: same model line, same tiers and variants, but the input is an existing image plus a prompt rather than a prompt alone. Use it for retouching, replacing or removing objects, restyling a scene, and for correcting or replacing text that already appears in the image. The difference that matters most for an editing pipeline is the default aspect_ratio: "auto": the output keeps the proportions of the image you sent, including ratios that are not in the preset list, so an edit does not silently reframe your asset.

​
Key capabilities

  • Keeps your shape: with the default aspect_ratio: "auto" and a single reference, the output preserves its aspect ratio exactly — measured in production, a 1200x1600 input (0.75) came back at 1086x1448 (0.75), and a 1024x768 input (1.3333) at 1448x1086 (1.3333)
  • Prompt-driven editing: describe the change in natural language instead of masking it by hand
  • Up to 16 references: send one image to retouch it, or several to compose a new image from them, each up to 20 MiB
  • Five quality tiers: quality accepts low, medium, high, xhigh and max. Editing is priced differently from generation — see Pricing below
  • Two models in one endpoint: variant selects flare (latency-optimised, the default) or sunburst, the editing-precision end of the line
  • Batch variants: request up to 10 edited variants of the same input in one call with num_images. Each output image is billed
  • Async processing: every request returns a task ID immediately. Poll the task endpoint or supply webhook_url to be notified on completion

​
Use cases

  • Photoshop and ComfyUI pipelines: replace a local editing step with an API call that returns the same frame proportions
  • Product photography retouching: change backgrounds, lighting or props without a reshoot
  • Localisation: replace on-image copy for another market while keeping the layout
  • Packaging revisions: update a label, claim or price on an approved key visual
  • Creative variations: generate up to 10 alternative treatments of one approved image for A/B testing
  • Clean-up: remove unwanted objects, watermarks or distractions from an existing asset

​
Edit images with GPT Image 2.5

Submit the source image or images plus an instruction to create an editing task. The API responds with a task ID; collect the result by polling or via webhook.

POST /v1/ai/text-to-image/gpt-image-2-5-edit

Create a new image editing task

GET /v1/ai/text-to-image/gpt-image-2-5-edit

List all GPT Image 2.5 Edit tasks with status

GET /v1/ai/text-to-image/gpt-image-2-5-edit/{task-id}

Get task status and results by ID

​
Parameters

​
Pricing

Editing sends your images to the model, and their input tokens dominate the cost, so it is priced differently from generation: flat units per output image by quality, with resolution not affecting the price. Every image in num_images is billed. The endpoint reference pages above are generated from the OpenAPI specification and are the authoritative, complete parameter list.

​
Frequently Asked Questions

GPT Image 2.5 Edit is an image editing API powered by OpenAI’s GPT Image 2.5 model line. You submit one or more source images plus an instruction and receive a task ID immediately. Poll the task endpoint or configure a webhook to receive the edited images when processing completes.
Yes, with the default aspect_ratio: "auto" and a single reference image: the output preserves its proportions, including ratios outside the preset list.When you send several references with different proportions, auto resolves to one of them and which one is decided by the model, not by the order you sent them in. If the output has to match a specific frame in that case, set an explicit aspect_ratio instead of relying on auto.
No. Describe the change in the prompt — what should change, rather than what the image already contains — and the model applies it to the region it refers to.
Up to 16, in order, each up to 20 MiB, with a limit of 64 MiB per request. They are used together as one visual context, so you can compose a new image from a subject, a background and a style reference in a single call.
Each entry of reference_images may be an HTTPS URL that is publicly reachable, a base64-encoded image, or an upload id returned by the uploads API. Supported formats are jpg, jpeg, png and webp.
GPT Image 2.5 generates a new image from a text prompt alone. GPT Image 2.5 Edit takes one or more existing images plus a prompt and returns a modified version. They share the model line, the tiers and the variants, and are priced differently.
Rate limits depend on your subscription tier. See Rate Limits for current limits.
Cost per output image depends on the quality tier, as flat units — see the table above. Resolution does not change the price of an edit. See the Pricing page for current rates.

​
Best practices

  • Say what changes: describe the modification, not the contents of the image the model can already see
  • Keep auto unless reframing: it is what preserves your source proportions. With several references of different shapes, set an explicit aspect_ratio if the output frame matters
  • Cite figures in order: with several references, refer to them by position in the prompt so the model can tell them apart
  • Use sunburst for precision edits: it is the editing end of the model line, at the same price as flare
  • Batch deliberately: num_images is billed per output image
  • Production integration: use webhook_url instead of polling for scalable applications
  • Error handling: implement retry logic with exponential backoff for 503 errors