> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qingbo.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# GPT Image 2.5
> Five quality levels for text-to-image and reference editing, on the Flare and Sunburst lines, billed from token usage
GPT Image 2.5 is the next generation of the official GPT Image line. It keeps the actions and parameters of GPT Image 2, widens quality from three levels to five, and re-scales the output usage of the levels that share a name. Two models are available, `gpt-image-2.5` (the Flare line) and `gpt-image-2.5-sunburst` (the Sunburst line); their request shape, value ranges and billing are identical, and they differ only in the trade-off between speed and editing precision. Switching between them means changing the `model` field alone.
## Available models
| Model ID | Trade-off | Suited to | Billing |
| ------------------------ | -------------------------------------- | --------------------------------------------------------------- | ----------------------- |
| `gpt-image-2.5` | Flare line, faster output | Everyday high-quality output, batch generation, quick drafts | From actual token usage |
| `gpt-image-2.5-sunburst` | Sunburst line, editing precision first | Production assets, advertising creative, multi-turn detail work | From actual token usage |
Both models carry the same rates, so the same set of parameters costs the same on either one; only the generated result differs. QWave never switches between them automatically.
## Quick start
```bash Text to image theme={"system"}
curl -X POST https://www.qingbo.dev/v1/tasks \
-H "Authorization: Bearer $WAVE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: image25-demo-001" \
-d '{
"model": "gpt-image-2.5",
"action": "generate",
"prompt": "A hand-thrown celadon teacup on raw linen, single north-facing window light, soft falloff, still life",
"aspect_ratio": "1:1",
"resolution": "1k",
"quality": "medium",
"n": 1
}'
```
```bash Reference editing theme={"system"}
curl -X POST https://www.qingbo.dev/v1/tasks \
-H "Authorization: Bearer $WAVE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: image25-edit-001" \
-d '{
"model": "gpt-image-2.5-sunburst",
"action": "edit",
"prompt": "Preserve the product and its package text, replace the background with a soft off-white studio, and add a natural shadow",
"image_urls": ["https://cdn.example.com/source.png"],
"aspect_ratio": "1:1",
"resolution": "2k",
"quality": "xhigh",
"n": 1
}'
```
A successful submission returns a `task_id`. Retrieve the result with [`GET /v1/tasks/{task_id}`](/en/api-reference/task/status), wait inline with [`Prefer: wait`](/en/api-reference/task/submit#in-request-waiting-prefer-wait), or configure a webhook.
## Request parameters
`gpt-image-2.5` or `gpt-image-2.5-sunburst`.
* `generate` — generate an image from text
* `edit` — edit reference images; `image_urls` is required
Image description or editing instruction.
Reference image URLs. Required for `edit`, up to 16 images.
One of `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `5:4`, `4:5`, `16:9`, `9:16`, `2:1`, `1:2`, `3:1`, `1:3`, `21:9`, `9:21`.
Output resolution: `1k`, `2k` or `4k`.
Quality level: `low`, `medium`, `high`, `xhigh` or `max`. `xhigh` and `max` exist only on 2.5; sending them to `gpt-image-2` returns `400` and is not downgraded silently. Quality has the largest effect on cost on this line — see Pricing below.
Number of images, fixed at `1`. Each request returns one image.
`auto`, `opaque` or `transparent`. Left to the model when omitted. A transparent background supports `png` and `webp` only.
`png`, `jpeg` or `webp`.
JPEG/WebP compression, `0`–`100`. Requires `output_format` set to `jpeg` or `webp`.
Moderation level: `auto` or `low`.
The shared `callback_url`, `callback_events`, `Prefer: wait`, `Idempotency-Key` and cost-ceiling headers are documented in [Submit Task](/en/api-reference/task/submit).
This line does not accept `mask_url` or `seed` — for masked inpainting, use [`gpt-image-2`](/en/api-reference/image/gpt-image/gpt-image-2). Any other parameter returns `400` and is not billed.
## Limits
| Condition | Limit |
| --------------------------- | ---------------------------------------------------------- |
| Per request | One image returned |
| `action: "edit"` | At least one reference image is required |
| `background: "transparent"` | `output_format` must be `png` or `webp` |
| Using `output_compression` | `output_format` must be explicitly set to `jpeg` or `webp` |
| Reference images | Up to 16 |
| `xhigh` / `max` quality | Accepted only by the two 2.5 models |
## Pricing
**Billed from actual token usage** across five dimensions: text input, cached text input, image input, cached image input and image output.
Rates are in `price_config` on `GET /v1/models` and in the console's Model Market. What a single call actually cost is the `cost` field on the task response — an integer quota at **500,000 quota = 1 USD**, not dollars.
Image input includes reference images. Cached rates apply only when the upstream response reports cache usage that can be settled. Otherwise, billing uses ordinary input and image-output usage.
### Holds and settlement
Submitting a task places a hold for the estimated usage; the task then settles from actual usage and the difference is released. The estimate is built from:
* **Output** — expected output tokens, looked up by aspect ratio, resolution and quality
* **Text input** — a floor of 32 tokens
* **Reference images** — 4,096 tokens each
Quality dominates the spread. At a given aspect ratio and resolution, expected output tokens form roughly this ladder: `medium` around 2× `low`, `high` around 9×, `xhigh` around 16×, and `max` around 36×. Resolution adds another layer, with `4k` several times `1k`. Combined, per-image cost spans two orders of magnitude. Aspect ratio matters too: at the same quality, `16:9` uses fewer output tokens than `1:1`.
Levels that share a name are not interchangeable across generations: `medium` and `high` on 2.5 are about a quarter of the output tokens of the same-named levels on GPT Image 2, and `max` on 2.5 is what corresponds to `high` on GPT Image 2. When migrating from `gpt-image-2`, re-estimate against the ladder on this page rather than carrying over the old cost expectations.
The estimated output tokens for every aspect-ratio / resolution / quality combination are in `price_config.image_usage_reservation` on `GET /v1/models`.
You are only billed for a successfully generated image. Failed and cancelled tasks, and tasks that return no usable image, are refunded in full. See [Task status](/en/api-reference/task/status) for the billing fields.
## Response
```json Completed task theme={"system"}
{
"task_id": "taski_example",
"model": "gpt-image-2.5",
"action": "generate",
"status": "completed",
"progress": "100%",
"result": {
"images": [
{
"url": ["https://cdn.example.com/result.png"],
"expires_at": 1789568757
}
]
},
"billing_status": "settled",
"cost": 6045
}
```
Generated images are returned in `result.images`, and `expires_at` is when that link is deleted (artifacts are kept for 7 days — see [Task status](/en/api-reference/task/status)). Failed and cancelled tasks release the hold in full. If an upstream success response contains no deliverable image, QWave marks the task as failed and refunds it.
## Related
* [GPT Image Series](/en/api-reference/image/gpt-image/overview)
* [GPT Image 2 Official](/en/api-reference/image/gpt-image/gpt-image-2)
* [GPT Image 1 and 1.5 Official](/en/api-reference/image/gpt-image/gpt-image-1)
* [Submit Task](/en/api-reference/task/submit)
* [Query Task Status](/en/api-reference/task/status)
* [Task System](/en/docs/task-system)