> ## 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 圖像生成與編輯

> gpt-image-2.5-flare-vip 和 gpt-image-2.5-sunburst-vip 異步圖片任務接入指南, 支持五檔質量, 像素尺寸, 透明背景和按實際 token 後付費

VIP 版通過 `POST /v1/images/generations` 建立圖片任務, 返回任務 ID. 任務完成後通過查詢接口獲取圖片 URL. VIP 版與普通版的共同點是都使用異步任務; 區別在模型名, size 格式和計價方式.

| 模型           | 請求中的 model                   |
| ------------ | ---------------------------- |
| Flare VIP    | `gpt-image-2.5-flare-vip`    |
| Sunburst VIP | `gpt-image-2.5-sunburst-vip` |

`gpt-image-2.5-vip` 是文檔中的系列名稱. 調用時請使用表中的完整模型名.

<Note>
  普通版同樣使用異步任務, 但按分辨率計價並使用比例形式的 size, 請查看獨立的 [GPT-Image-2.5 文檔](../gpt-image-2.5/generation). VIP 版使用像素尺寸, 並按實際 token 結算.
</Note>

<Note>
  **中國大陸用戶請注意：** 中國大陸用戶請使用 `https://toapis.cn` 作為接口地址（Base URL）。文檔示例中的 `https://toapis.com` 請替換為 `https://toapis.cn`。
</Note>

API Key 可在 [控制台](https://toapis.com/dashboard) 建立.

## 快速開始

將自己的 API Key 設置為環境變量 `TOAPIS_API_KEY`, 提交任務:

```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": "兒童繪本風格, 一位獸醫用聽診器給小水獺檢查心跳",
    "quality": "low",
    "size": "1024x1024",
    "n": 1
  }'
```

提交響應示例:

```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": {}
}
```

保存返回的 `id`, 將下方的 `TASK_ID` 替換為該值後查詢:

```bash theme={null}
curl --fail-with-body \
  --url https://toapis.com/v1/images/generations/TASK_ID \
  --header "Authorization: Bearer $TOAPIS_API_KEY"
```

任務可能經過 `pending`, `queued`, `in_progress`, 最終進入 `completed` 或 `failed`. `completed` 時從 `result.data` 讀取圖片 URL, `failed` 時讀取 `error`. 建議每隔數秒查詢一次. 完整字段見 [圖片任務狀態接口](../../tasks/image-status).

提交成功表示任務已建立. 請等到 `completed` 後再下載圖片; 等待期間繼續查詢同一個任務 ID. 高質量請求耗時較長, 請保持輪詢, 不要重複提交.

## 生成請求參數

<ParamField header="Authorization" type="string" required>
  使用 `Bearer YOUR_TOAPIS_API_KEY` 認證.
</ParamField>

<ParamField body="model" type="string" required>
  `gpt-image-2.5-flare-vip` 或 `gpt-image-2.5-sunburst-vip`.
</ParamField>

<ParamField body="prompt" type="string" required>
  圖片描述. 編輯時描述需要保留和修改的內容.
</ParamField>

<ParamField body="quality" type="string" default="high">
  支持 `low`, `medium`, `high`, `xhigh`, `max` 五檔, 默認 `high`. 使用小寫值.

  quality 影響生成質量和實際輸出 token. 相同 quality 的圖片也可能因尺寸和內容不同而產生不同費用.
</ParamField>

<ParamField body="size" type="string" default="1024x1024">
  輸出像素尺寸, 使用 `寬x高` 格式. 例如 `1024x1024`, `1536x1024`, `1024x1536`, `1280x1024`.

  支持上游允許的自定義像素尺寸, 不限於上述示例. 合法尺寸範圍以接口校驗為準. VIP 示例不使用 `1:1` 這樣的比例值, 也不需要額外傳入 resolution.
</ParamField>

<ParamField body="background" type="string">
  可選的背景參數. 傳入 `"transparent"` 生成透明背景圖片, 不傳此參數時正常生圖.

  文生圖和參考圖編輯均可使用. 一般生圖請直接省略此欄位.
</ParamField>

<ParamField body="n" type="integer" default={1}>
  每次請求使用 `1`, 生成一張圖片.
</ParamField>

## 透明背景

生成請求中加入 `"background": "transparent"` 即可得到透明背景的圖片. 不傳此欄位時正常生圖.

```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": "一個紅色圓形貼紙, 背景透明",
    "quality": "low",
    "size": "1024x1024",
    "background": "transparent",
    "n": 1
  }'
```

提交後同樣透過任務 ID 查詢, 從 `result.data` 讀取圖片 URL.

## 參考圖編輯

編輯使用 `POST /v1/images/edits`, 請求為 `multipart/form-data`. 將本地圖片放在 `image` 文件字段中, 同時傳入 `model`, `prompt`, `quality`, `size` 和 `n`. 編輯同樣是異步任務, 提交後返回任務 ID, 查詢方式與生成相同.

下例使用 Sunburst VIP, 給 `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=保留原圖中的小水獺和獸醫, 給小水獺增加一條黃色圍巾' \
  --form 'image=@otter.png;type=image/png' \
  --form 'quality=low' \
  --form 'size=1024x1024' \
  --form 'n=1'
```

讓 curl 自動設置 multipart 的 Content-Type 和 boundary. 使用響應中的任務 ID 輪詢查詢接口, 從 `result.data` 讀取編輯後的圖片 URL.

Flare VIP 也支持同樣的編輯方式, 將 model 改為 `gpt-image-2.5-flare-vip` 即可. 參考圖輸入會產生圖片輸入 token 費用.

## token 價格

以下為 2026-09-09 核對的標準價格, 兩個 VIP 模型相同, 按官方 token 單價的 8 折計費:

| 類型     | USD/百萬 token |
| ------ | -----------: |
| 文本輸入   |         4.00 |
| 緩存文本輸入 |         1.00 |
| 圖片輸入   |         6.40 |
| 緩存圖片輸入 |         1.60 |
| 圖片輸出   |        24.00 |

五檔 quality 共用上述 token 單價. VIP 沒有按 quality 固定的每張價格, 任務完成後按實際用量結算. 提交任務時會先預扣, 完成後按實際文本和圖片 token 結算, 多退少補. 調用前仍需有足夠的賬戶餘額和 API Key 額度.

費用公式, 單位為 USD:

```text theme={null}
費用 = (
  未緩存文本輸入 token * 4
  + 緩存文本輸入 token * 1
  + 未緩存圖片輸入 token * 6.4
  + 緩存圖片輸入 token * 1.6
  + 圖片輸出 token * 24
) / 1,000,000
```

例如一次 `low` 質量的 1024x1024 文生圖包含 27 個文本輸入 token 和 196 個圖片輸出 token, 費用為:

```text theme={null}
(27 * 4 + 196 * 24) / 1,000,000 = $0.004812
```

一次參考圖編輯實測包含 21 個文本輸入 token, 1024 個圖片輸入 token 和 196 個圖片輸出 token. 公式金額為 $0.0113416, 按平台額度最小單位捨入後實扣 $0.011342. 這些是具體請求的示例, 不代表同一質量下每張圖的固定費用.

賬戶專屬定價或折扣可能不同, 最新價格以 [模型定價頁](https://toapis.com/pricing) 和賬戶實際配置為準. 最終扣費可在使用日誌中核對.

## 從普通版切換

1. 將完整模型名改為對應的 `-vip` 模型名.
2. 將 size 從比例改為像素尺寸, 並省略 resolution.
3. 文生圖和參考圖編輯都通過任務 ID 輪詢結果, 從 `result.data` 讀取圖片 URL.
4. 參考圖編輯改用 `/v1/images/edits` 上傳圖片文件.
5. 按實際 token 預估費用.

普通版的任務提交和查詢示例見 [GPT-Image-2.5 文檔](../gpt-image-2.5/generation).