> ## 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 文檔](https://docs.toapis.com/docs/zh-Hant/api-reference/images/gpt-image-2.5/generation.md). VIP 版使用像素尺寸, 並按實際 token 結算.

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

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`. 建議每隔數秒查詢一次. 完整字段見 [圖片任務狀態接口](https://docs.toapis.com/docs/zh-Hant/api-reference/tasks/image-status.md).

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

## 生成請求參數

**Authorization** `string` *required*

使用 `Bearer YOUR_TOAPIS_API_KEY` 認證.

**model** `string` *required*

`gpt-image-2.5-flare-vip` 或 `gpt-image-2.5-sunburst-vip`.

**prompt** `string` *required*

圖片描述. 編輯時描述需要保留和修改的內容.

**quality** `string` (default: high)

支持 `auto`, `low`, `medium`, `high`, `xhigh`, `max` 六檔, 默認 `high`. 使用小寫值. `auto` 表示由上游模型為每個請求自動選擇質量檔位.

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

**size** `string` (default: 1024x1024)

輸出像素尺寸, 使用 `寬x高` 格式. 例如 `1024x1024`, `1536x1024`, `1024x1536`, `1280x1024`.

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

自定義像素尺寸需要滿足以下比例值: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `5:4`, `4:5`, `21:9`.

**background** `string`

可選的背景參數. 傳入 `"transparent"` 生成透明背景圖片, 不傳此參數時正常生圖.

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

**n** `integer` (default: 1)

每次請求使用 `1`, 生成一張圖片.

**reference\_images** `string[]`

可選的參考圖 URL 列表, 用於圖生圖. 圖片地址需要能被服務端訪問. 本接口只支持圖片 URL, 不支持本地文件上傳或 base64; 本地圖片請先通過 [上傳圖片接口](https://docs.toapis.com/docs/zh-Hant/api-reference/uploads/images.md) 獲取 URL.

也兼容 `image_urls`. 選擇其中一個字段即可. 生成接口傳入參考圖 URL 時按圖生圖處理.

## 透明背景

生成請求中加入 `"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`. 異步編輯僅支持圖片 URL, 將 URL 放在 `image` 字段中, 同時傳入 `model`, `prompt`, `quality`, `size` 和 `n`. 不支持本地文件上傳或 base64 圖片. 編輯同樣是異步任務, 提交後返回任務 ID, 查詢方式與生成相同.

下例使用 Sunburst VIP, 給參考圖中的小水獺增加黃色圍巾. 請將示例 URL 替換為自己的圖片 URL:

```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=https://example.com/otter.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` 並傳入圖片 URL.
5. 按實際 token 預估費用.

普通版的任務提交和查詢示例見 [GPT-Image-2.5 文檔](https://docs.toapis.com/docs/zh-Hant/api-reference/images/gpt-image-2.5/generation.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.