> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magnific.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GPT Image 2.5 Edit – Image Editing API | Magnific API

> Edit images with GPT Image 2.5. Prompt-driven retouching that keeps your source aspect ratio, five quality tiers, up to 16 references and 10 variants per call.

<Card title="OpenAI GPT Image 2.5 – editing" icon="image">
  Prompt-driven editing that keeps the aspect ratio of the images you send, with five quality tiers and two selectable models.
</Card>

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 <a href="/api-reference/text-to-image/gpt-image-2-5/overview">GPT Image 2.5</a>: 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.

<div className="my-11">
  <Columns cols={2}>
    <Card title="POST /v1/ai/text-to-image/gpt-image-2-5-edit" icon="image" href="/api-reference/text-to-image/gpt-image-2-5-edit/edit">
      Create a new image editing task
    </Card>

    <Card title="GET /v1/ai/text-to-image/gpt-image-2-5-edit" icon="list" href="/api-reference/text-to-image/gpt-image-2-5-edit/gpt-image-2-5-edit-tasks">
      List all GPT Image 2.5 Edit tasks with status
    </Card>

    <Card title="GET /v1/ai/text-to-image/gpt-image-2-5-edit/{task-id}" icon="magnifying-glass" href="/api-reference/text-to-image/gpt-image-2-5-edit/task-by-id">
      Get task status and results by ID
    </Card>
  </Columns>
</div>

### Parameters

| Parameter          | Type      | Required | Default  | Description                                                                                                                               |
| ------------------ | --------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`           | `string`  | Yes      | -        | The edit to apply, described in natural language                                                                                          |
| `reference_images` | `array`   | Yes      | -        | 1 to 16 images to edit, in order. Each may be an HTTPS URL, a base64 image or an upload id                                                |
| `quality`          | `string`  | No       | `medium` | Quality tier: `low`, `medium`, `high`, `xhigh` or `max`                                                                                   |
| `variant`          | `string`  | No       | `flare`  | Which model renders the request: `flare` (latency) or `sunburst` (editing precision)                                                      |
| `resolution`       | `string`  | No       | `1k`     | Output resolution tier: `1k`, `2k` or `4k`. Unlike generation, it does **not** change the price of an edit                                |
| `aspect_ratio`     | `string`  | No       | `auto`   | `auto` keeps the aspect ratio of the reference images. Pick a preset such as `square_1_1` or `widescreen_16_9` to reframe on purpose      |
| `num_images`       | `integer` | No       | `1`      | Number of edited variants to return, up to 10. Each image is billed                                                                       |
| `output_format`    | `string`  | No       | `png`    | `png`, `jpeg` or `webp`. `output_compression` applies to the last two                                                                     |
| `background`       | `string`  | No       | -        | `transparent`, `opaque` or `auto`. A transparent result needs `png` or `webp`                                                             |
| `moderation`       | `string`  | No       | `auto`   | Strictness of the model provider's own filter: `auto` or `low`. Applied on top of Freepik's platform moderation, which cannot be disabled |
| `webhook_url`      | `string`  | No       | -        | URL called when the task completes                                                                                                        |

### 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.

|                        | `low` | `medium` | `high`, `xhigh`, `max` |
| ---------------------- | ----- | -------- | ---------------------- |
| units per output image | x1    | x4       | x6                     |

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

<AccordionGroup>
  <Accordion title="What is GPT Image 2.5 Edit and how does it work?">
    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.
  </Accordion>

  <Accordion title="Does the edit keep the aspect ratio of my image?">
    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`.
  </Accordion>

  <Accordion title="Do I need a mask to edit part of an image?">
    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.
  </Accordion>

  <Accordion title="How many reference images can I send?">
    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.
  </Accordion>

  <Accordion title="What image inputs are accepted?">
    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.
  </Accordion>

  <Accordion title="What is the difference between GPT Image 2.5 Edit and GPT Image 2.5?">
    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.
  </Accordion>

  <Accordion title="What are the rate limits for GPT Image 2.5 Edit?">
    Rate limits depend on your subscription tier. See [Rate Limits](/ratelimits) for current limits.
  </Accordion>

  <Accordion title="How much does GPT Image 2.5 Edit cost?">
    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](/pricing) for current rates.
  </Accordion>
</AccordionGroup>

## 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

## Related APIs

* **[GPT Image 2.5](/api-reference/text-to-image/gpt-image-2-5/overview)**: generate images from a prompt with the same model line
* **[GPT Image 2 Edit](/api-reference/text-to-image/gpt-image-2-edit/overview)**: the previous generation, with three quality tiers
* **[Nano Banana Pro](/api-reference/text-to-image/post-nano-banana-pro)**: Google Gemini image generation and editing
* **[Seedream 5 Pro Edit](/api-reference/text-to-image/post-seedream-v5-pro-edit)**: high-resolution reference-based editing