> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.
# GPT-Image-2.5 VIP Image Generation and Editing
> Async task guide for gpt-image-2.5-flare-vip and gpt-image-2.5-sunburst-vip, with five quality levels, pixel dimensions, transparent backgrounds, and postpaid billing by actual token usage
The VIP tier creates an image task through `POST /v1/images/generations` and returns a task ID. After the task finishes, retrieve the image URL through the status endpoint. Like the standard tier, the VIP tier runs as an async task; the differences are the model names, the `size` format, and the billing model.
| Model | `model` in the request |
| ------------ | ---------------------------- |
| Flare VIP | `gpt-image-2.5-flare-vip` |
| Sunburst VIP | `gpt-image-2.5-sunburst-vip` |
`gpt-image-2.5-vip` is the series name used in this document. Always pass the full model name from the table.
The standard tier also runs as an async task, but it is priced by resolution and uses ratio values for `size`; see the separate [GPT-Image-2.5 documentation](../gpt-image-2.5/generation). The VIP tier uses pixel dimensions and settles by actual token usage.
**Note for users in mainland China:** Please use `https://toapis.cn` as the API endpoint (Base URL). Replace `https://toapis.com` with `https://toapis.cn` in the examples in this document.
Create an API Key in the [ToAPIs console](https://toapis.com/dashboard).
## Quick Start
Set your API Key as the `TOAPIS_API_KEY` environment variable, then submit the task:
```bash theme={null}
curl --fail-with-body --request POST \
--url https://toapis.com/v1/images/generations \
--header "Authorization: Bearer $TOAPIS_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "gpt-image-2.5-flare-vip",
"prompt": "Children's picture book style, a veterinarian listening to a baby otter's heartbeat with a stethoscope",
"quality": "low",
"size": "1024x1024",
"n": 1
}'
```
Example submit response:
```json theme={null}
{
"id": "tsk_img_example",
"object": "generation.task",
"model": "gpt-image-2.5-flare-vip",
"status": "pending",
"progress": 0,
"created_at": 1788951900,
"metadata": {}
}
```
Save the returned `id`, replace `TASK_ID` below with that value, and query the result:
```bash theme={null}
curl --fail-with-body \
--url https://toapis.com/v1/images/generations/TASK_ID \
--header "Authorization: Bearer $TOAPIS_API_KEY"
```
A task moves through `pending`, `queued`, and `in_progress`, and finally reaches `completed` or `failed`. On `completed`, read the image URL from `result.data`; on `failed`, read `error`. Poll every few seconds. The full set of fields is documented in [Image Task Status](../../tasks/image-status).
A successful submit only means the task was created. Wait until `completed` before downloading the image, and keep polling the same task ID while you wait. High-quality requests take longer, so keep polling instead of resubmitting.
## Generation Request Parameters
Authenticate with `Bearer YOUR_TOAPIS_API_KEY`.
`gpt-image-2.5-flare-vip` or `gpt-image-2.5-sunburst-vip`.
Description of the image. When editing, describe what to keep and what to change.
Five levels are supported: `low`, `medium`, `high`, `xhigh`, and `max`. The default is `high`. Use lowercase values.
Quality affects the generation result and the actual output tokens. Images with the same quality can still cost different amounts depending on dimensions and content.
Output pixel dimensions in `widthxheight` format, for example `1024x1024`, `1536x1024`, `1024x1536`, `1280x1024`.
Custom pixel dimensions allowed by the upstream provider are supported, not only the examples above. The valid size range is enforced by the endpoint validation. VIP examples do not use ratio values such as `1:1`, and no separate `resolution` is required.
Optional background setting. Set `"transparent"` to generate an image with a transparent background. Omit this field for normal image generation.
Works with both text-to-image requests and reference image editing.
Use `1` per request to generate one image.
## Transparent Background
Add `"background": "transparent"` to the generation request to get an image with a transparent background. Omit the field for normal generation.
```bash theme={null}
curl --fail-with-body --request POST \
--url https://toapis.com/v1/images/generations \
--header "Authorization: Bearer $TOAPIS_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "gpt-image-2.5-flare-vip",
"prompt": "A red circular sticker on a transparent background",
"quality": "low",
"size": "1024x1024",
"background": "transparent",
"n": 1
}'
```
The task is queried by task ID as usual; read the image URL from `result.data`.
## Reference Image Editing
Editing uses `POST /v1/images/edits` with a `multipart/form-data` request. Put the local image in the `image` file field and pass `model`, `prompt`, `quality`, `size`, and `n` alongside it. Editing is also an async task: the submit returns a task ID, and you query the result the same way as generation.
The example below uses Sunburst VIP to add a yellow scarf to the baby otter in `otter.png`:
```bash theme={null}
curl --fail-with-body --request POST \
--url https://toapis.com/v1/images/edits \
--header "Authorization: Bearer $TOAPIS_API_KEY" \
--form 'model=gpt-image-2.5-sunburst-vip' \
--form 'prompt=Keep the baby otter and the veterinarian from the original image, and add a yellow scarf to the baby otter' \
--form 'image=@otter.png;type=image/png' \
--form 'quality=low' \
--form 'size=1024x1024' \
--form 'n=1'
```
Let curl set the multipart Content-Type and boundary automatically. Poll the status endpoint with the returned task ID and read the edited image URL from `result.data`.
Flare VIP supports the same editing approach; change the model to `gpt-image-2.5-flare-vip`. Reference image input incurs image input token costs.
## Token Pricing
The prices below are standard prices verified on 2026-09-09. Both VIP models are the same and are billed at 20% off the official token unit prices:
| Type | USD per million tokens |
| ------------------ | ---------------------: |
| Text input | 4.00 |
| Cached text input | 1.00 |
| Image input | 6.40 |
| Cached image input | 1.60 |
| Image output | 24.00 |
All five quality levels share these token unit prices. VIP has no fixed per-image price tied to quality; the task is settled by actual usage after it completes. Submitting a task pre-authorizes an amount, and the final charge is settled from the actual text and image tokens after completion, with any difference refunded or charged. You still need sufficient account balance and API Key quota before calling.
Cost formula, in USD:
```text theme={null}
cost = (
uncached text input tokens * 4
+ cached text input tokens * 1
+ uncached image input tokens * 6.4
+ cached image input tokens * 1.6
+ image output tokens * 24
) / 1,000,000
```
For example, a `low` quality 1024x1024 text-to-image request with 27 text input tokens and 196 image output tokens costs:
```text theme={null}
(27 * 4 + 196 * 24) / 1,000,000 = $0.004812
```
One measured reference image edit contained 21 text input tokens, 1024 image input tokens, and 196 image output tokens. The formula gives $0.0113416, which is charged as $0.011342 after rounding to the smallest platform quota unit. These are examples for specific requests and do not represent a fixed cost per image at the same quality.
Account-specific pricing or discounts may differ; check the [model pricing page](https://toapis.com/pricing) and your account configuration for the latest prices. You can verify the final charge in the usage logs.
## Switching from the Standard Tier
1. Change the full model name to the matching `-vip` model name.
2. Change `size` from a ratio to pixel dimensions, and omit `resolution`.
3. For both text-to-image and reference image editing, poll the result by task ID and read the image URL from `result.data`.
4. For reference image editing, switch to `/v1/images/edits` and upload the image file.
5. Estimate cost from actual tokens.
For async submission and task polling examples in the standard tier, see the [GPT-Image-2.5 documentation](../gpt-image-2.5/generation).