> ## 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 – Text-to-Image API | Magnific API

> Generate images with GPT Image 2.5. Five quality tiers up to max, two models, native transparent backgrounds and an auto aspect ratio that keeps your reference shape.

<Card title="OpenAI GPT Image 2.5" icon="wand-magic-sparkles">
  Text-to-image generation with five quality tiers, two selectable models, native transparent backgrounds and an `auto` aspect ratio that lets the model choose the shape.
</Card>

GPT Image 2.5 is a text-to-image API that turns a written prompt into one or more images. It is the successor to <a href="/api-reference/text-to-image/gpt-image-2/overview">GPT Image 2</a>: lower latency at every tier, two extra quality tiers (`xhigh` and `max`), transparent backgrounds as a first-class option, and an `auto` aspect ratio. It keeps what the previous generation is chosen for — close adherence to long, specific prompts and legible text rendered inside the image. To edit an existing image instead of generating from scratch, see <a href="/api-reference/text-to-image/gpt-image-2-5-edit/overview">GPT Image 2.5 Edit</a>.

### Key capabilities

* **Five quality tiers**: `quality` accepts `low`, `medium`, `high`, `xhigh` and `max`. The tier changes render quality and latency, so the same prompt can be drafted cheaply and finalised at the top of the scale
* **Two models in one endpoint**: `variant` selects `flare` (latency-optimised, the default) or `sunburst` (editing-precision). Same parameters, same price
* **Auto aspect ratio**: `aspect_ratio` defaults to `auto`, which lets the model choose the shape instead of forcing a preset
* **Transparent backgrounds**: `background: "transparent"` is native. Use it with `png` or `webp`, the two formats that carry an alpha channel
* **Batch generation**: request up to 10 images in a single call with `num_images`. Each image in the batch 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

* **Marketing and advertising**: on-brand key visuals where the headline or product name has to be readable inside the image
* **Logos, icons and overlays**: assets that need a real alpha channel rather than a white box behind them
* **Packaging and print mockups**: labels, boxes and signage that need real text rather than text-shaped noise
* **Product and UI concepting**: interface screens, dashboards and device mockups with legible captions
* **Content pipelines at scale**: batch variants at `low`, review, then re-render the winner at `max`

### Generate images with GPT Image 2.5

Submit a prompt to create a generation 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" icon="wand-magic-sparkles" href="/api-reference/text-to-image/gpt-image-2-5/generate">
      Create a new image generation task
    </Card>

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

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

### Parameters

| Parameter       | Type      | Required | Default  | Description                                                                                                                                                      |
| --------------- | --------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`        | `string`  | Yes      | -        | Text description of the image to generate, up to 32,000 characters                                                                                               |
| `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`. Also multiplies the credit cost — see Pricing below                                                                  |
| `aspect_ratio`  | `string`  | No       | `auto`   | `auto` lets the model choose, or pick a preset such as `square_1_1`, `widescreen_16_9`, `banner_3_1`. Combined with `resolution` it selects the exact pixel size |
| `num_images`    | `integer` | No       | `1`      | Number of images to generate in one request, 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

The `quality` tier sets the price per image and `resolution` multiplies it:

|                   | `1k` | `2k` | `4k` |
| ----------------- | ---- | ---- | ---- |
| credits per image | x1   | x2   | x3   |

Every image in `num_images` is billed, so a `4k` request for 4 images costs
twelve times a single `1k` image of the same quality tier.

`xhigh` and `max` are currently billed at the `high` price.

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 and how does it work?">
    GPT Image 2.5 is a text-to-image API powered by OpenAI's GPT Image 2.5 model line. You submit a text prompt and receive a task ID immediately. Poll the task endpoint or configure a webhook to receive the generated images when processing completes.
  </Accordion>

  <Accordion title="What does the auto aspect ratio do?">
    `auto` is the default and lets the model choose the shape of the output instead of forcing one of the presets. It is most useful on the edit endpoint, where the output then keeps the aspect ratio of the images you sent, including ratios that are not in the preset list. Note that `auto` only leaves the size free at `resolution: "1k"`; at `2k` and `4k` it renders a square at that tier.
  </Accordion>

  <Accordion title="What is the difference between the flare and sunburst variants?">
    They are the two models of the GPT Image 2.5 line, offered on the same endpoint with the same parameters and the same price. `flare` is optimised for latency and is the default; `sunburst` is the editing-precision end of the line. Requests that do not set `variant` always resolve to `flare`.
  </Accordion>

  <Accordion title="How do I get a transparent background?">
    Send `background: "transparent"` together with an `output_format` that has an alpha channel — `png` or `webp`. Asking for a transparent background with `jpeg` returns a 400, because JPEG cannot carry transparency and silently flattening it would corrupt the asset you asked for.
  </Accordion>

  <Accordion title="What do the xhigh and max quality tiers add?">
    They extend the scale past `high`, spending more provider compute for the most demanding renders. They are currently billed at the `high` price.
  </Accordion>

  <Accordion title="What is the difference between GPT Image 2.5 and GPT Image 2?">
    GPT Image 2.5 is faster at every tier, adds the `xhigh` and `max` tiers, exposes a selectable model through `variant`, supports transparent backgrounds natively, and defaults to an `auto` aspect ratio. GPT Image 2 remains available with its three tiers and its `square_1_1` default.
  </Accordion>

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

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

## Best practices

* **Tier the workflow**: draft at `quality: "low"`, review, then re-run the winning prompt at a higher tier. The prompt does not need to change
* **Leave the shape to the model**: keep the default `aspect_ratio: "auto"` unless the output has to fit a fixed frame, and pick a preset when it does
* **Batch deliberately**: `num_images` is billed per image. Batch at `low` for exploration, generate single images at the top tiers
* **Write text explicitly**: put the exact string you want rendered in quotes inside the prompt, and keep it short
* **Pick the format before the background**: a transparent render needs `png` or `webp`
* **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 Edit](/api-reference/text-to-image/gpt-image-2-5-edit/overview)**: edit existing images with the same model line, tiers and variants
* **[GPT Image 2](/api-reference/text-to-image/gpt-image-2/overview)**: the previous generation, with three quality tiers
* **[Nano Banana Pro](/api-reference/text-to-image/post-nano-banana-pro)**: Google Gemini image generation, also strong at in-image text
* **[Seedream 5 Pro](/api-reference/text-to-image/post-seedream-v5-pro)**: high-resolution text-to-image with a generate and edit split