> ## 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 Edit – Image Editing API | Magnific API

> Edit existing images with GPT Image 2. Prompt-driven retouching, object and style changes, three quality tiers, up to 10 variants per call, no mask needed.

<Card title="OpenAI GPT Image 2 – editing" icon="image">
  Prompt-driven editing of existing images, with the same three quality tiers as GPT Image 2 generation and its own pricing.
</Card>

GPT Image 2 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/overview">GPT Image 2</a>: same model, same three quality tiers, same batch limit, 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.

### Key capabilities

* **Prompt-driven editing**: describe the change in natural language instead of masking it by hand
* **Three quality tiers**: `quality` accepts `low`, `medium` and `high`. The tier changes both the render quality and the credit cost per output image — editing is priced differently from generation, see Pricing below
* **Batch variants**: request up to 10 edited variants of the same input in one call with `num_images`. Each output image is billed
* **In-image text edits**: legible text rendering carries over to editing, so labels and copy inside the image can be corrected or replaced
* **Async processing**: every request returns a task ID immediately. Poll the task endpoint or supply `webhook_url` to be notified on completion

### Use cases

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

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-edit" icon="image" href="/api-reference/text-to-image/gpt-image-2-edit/edit">
      Create a new image editing task
    </Card>

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

    <Card title="GET /v1/ai/text-to-image/gpt-image-2-edit/{task-id}" icon="magnifying-glass" href="/api-reference/text-to-image/gpt-image-2-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                                                           |
| `quality`       | `string`  | No       | `high`       | Quality and cost tier: `low`, `medium` or `high`                                                           |
| `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       | `square_1_1` | Shape of the output, e.g. `square_1_1`, `widescreen_16_9`, `banner_3_1`                                    |
| `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       | -            | `opaque` or `auto`. `auto` may return transparency, which only `png` and `webp` can keep                   |
| `moderation`    | `string`  | No       | `auto`       | Strictness of the model provider's own filter: `auto` or `low`                                             |
| `webhook_url`   | `string`  | No       | -            | URL called when the task completes                                                                         |

The source images are supplied on the request body alongside the prompt. The endpoint reference pages above are generated from the OpenAPI specification and are the authoritative, complete parameter list, including the exact field and accepted formats for the input images.

### Pricing

Editing sends your source images to the model, and their input tokens dominate
the cost, so it is not priced like a generation of the same size:

| `quality` | relative cost per output image |
| --------- | ------------------------------ |
| `low`     | x1                             |
| `medium`  | x4                             |
| `high`    | x6                             |

`resolution` does not affect the price of an edit — the input images set the
cost and the output size barely moves it. Every image in `num_images` is billed.

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What is GPT Image 2 Edit and how does it work?">
    GPT Image 2 Edit is an image editing API powered by OpenAI's GPT Image 2 model. You submit one or more source images together with a text 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="Do I need to supply a mask?">
    No. The edit is described in the prompt rather than painted as a mask. Be specific about what should change and what must stay the same, since the model decides the region itself.
  </Accordion>

  <Accordion title="What does the quality parameter change?">
    `quality` selects one of three tiers — `low`, `medium` or `high`. A higher tier spends more compute per output image, which improves detail and text fidelity, and costs more credits per image: a `high` edit costs six times a `low` one, and `medium` four times.
  </Accordion>

  <Accordion title="How many edited variants can I request at once?">
    Up to 10, via `num_images`. Every output image is billed at the tier you selected, so a request for 10 variants at `high` costs ten times a single `high` image.
  </Accordion>

  <Accordion title="What is the difference between GPT Image 2 and GPT Image 2 Edit?">
    GPT Image 2 generates a new image from a text prompt alone. GPT Image 2 Edit starts from images you provide and modifies them. Both use the same model, the same three quality tiers and the same batch limit, and both bill per output image.
  </Accordion>

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

  <Accordion title="How much does GPT Image 2 Edit cost?">
    Cost per output image depends on the `quality` tier you request. See the [Pricing page](/pricing) for current rates and subscription options.
  </Accordion>
</AccordionGroup>

## Best practices

* **Name what stays**: state explicitly which parts of the image must be preserved, not only what should change
* **One change at a time**: a single, clearly scoped edit per request is more reliable than a list of unrelated changes
* **Tier the workflow**: explore variants at `quality: "low"`, then re-run the chosen instruction at `quality: "high"`
* **Batch deliberately**: `num_images` is billed per output image, so batch at `low` and finalise at `high`
* **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](/api-reference/text-to-image/gpt-image-2/overview)**: generate a new image from a text prompt with the same model
* **[Seedream 5 Pro Edit](/api-reference/text-to-image/post-seedream-v5-pro-edit)**: reference-image editing with resolution-based tiers
* **[Reimagine Flux](/api-reference/text-to-image/reimagine-flux/post-reimagine-flux)**: re-generate variations of an existing image
* **[Skin Enhancer](/api-reference/skin-enhancer/overview)**: specialised portrait and skin retouching