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

> gpt-image-2.5-flare 和 gpt-image-2.5-sunburst 普通版接入指南, 包含異步任務, 參考圖, 透明背景, 固定 high 質量和按分辨率計價

普通版通過 `POST /v1/images/generations` 建立圖片任務, 返回任務 ID. 任務完成後通過查詢接口獲取圖片 URL. 兩個模型使用相同的請求格式:

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

`gpt-image-2.5` 是系列名稱. 調用時請填寫表中的完整模型名.

<Note>
  本文介紹普通版. 需要按實際 token 計費時, 請使用獨立的 [GPT-Image-2.5 VIP 文檔](../gpt-image-2.5-vip/generation). 兩版都使用異步任務, 主要區別在 size 格式和計價方式.
</Note>

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

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

## 快速開始

將自己的 ToAPIs 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",
    "prompt": "兒童繪本風格, 一位獸醫用聽診器給小水獺檢查心跳",
    "quality": "high",
    "size": "1:1",
    "resolution": "1K",
    "n": 1
  }'
```

提交響應示例:

```json theme={null}
{
  "id": "tsk_img_example",
  "object": "generation.task",
  "model": "gpt-image-2.5-flare",
  "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` 或 `gpt-image-2.5-sunburst`.
</ParamField>

<ParamField body="prompt" type="string" required>
  圖片描述. 使用參考圖時, 描述需要保留的主體和需要修改的內容.
</ParamField>

<ParamField body="quality" type="string" default="high">
  當前普通版 W8X 渠道固定使用 `high`, 可省略此參數. 傳入其他字符串值會被忽略, 統一使用 `high`. Playground 不展示質量選項.

  當前普通版按 resolution 定價.
</ParamField>

<ParamField body="size" type="string" default="1:1">
  畫面比例, 例如 `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `5:4`, `4:5`, `16:9`, `9:16`, `21:9`.

  推薦使用比例並顯式填寫 resolution. 服務端根據二者計算輸出像素尺寸. 普通版的比例寫法與 VIP 版的像素尺寸寫法不同.
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  分辨率檔位, 支持 `1K`, `2K`, `4K`, 也接受小寫形式. 該字段決定普通版的計價檔位.
</ParamField>

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

  文生圖和帶 `reference_images` 的圖生圖均可使用. 一般生圖請直接省略此欄位.
</ParamField>

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

<ParamField body="reference_images" type="string[]">
  可選的參考圖 URL 列表. 圖片地址需要能被服務端訪問. 本地圖片請先通過 [上傳圖片接口](../../uploads/images) 獲取 URL.

  也兼容 `image_urls`. 選擇其中一個字段即可. 本接口示例使用 URL 參考圖; 需要直接上傳本地文件進行編輯時, 請參考 [VIP 圖片編輯](../gpt-image-2.5-vip/generation).
</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",
    "prompt": "一個紅色圓形貼紙, 背景透明",
    "quality": "high",
    "size": "1:1",
    "resolution": "1K",
    "background": "transparent",
    "n": 1
  }'
```

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

## 比例和分辨率示例

| size   | 1K          | 2K          | 4K          |
| ------ | ----------- | ----------- | ----------- |
| `1:1`  | `1024x1024` | `2048x2048` | `2880x2880` |
| `3:2`  | `1536x1024` | `2048x1360` | `3520x2336` |
| `2:3`  | `1024x1536` | `1360x2048` | `2336x3520` |
| `16:9` | `1536x864`  | `2048x1152` | `3840x2160` |
| `9:16` | `864x1536`  | `1152x2048` | `2160x3840` |

`4K` 表示分辨率檔位, 實際長寬取決於畫面比例, 例如正方形 4K 輸出為 `2880x2880`.

## 參考圖生成

使用同一個生成接口, 增加 `reference_images`. 下例使用 Sunburst, 返回值仍然是異步任務:

```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-sunburst",
    "prompt": "保留參考圖中的小水獺和獸醫, 給小水獺增加一條黃色圍巾",
    "reference_images": ["https://example.com/otter.png"],
    "quality": "high",
    "size": "1:1",
    "resolution": "2K",
    "n": 1
  }'
```

將 `https://example.com/otter.png` 替換為自己的參考圖 URL, 然後使用返回的任務 ID 查詢結果.

## 價格

以下為 2026-09-09 核對的標準價格, 每次生成一張圖片, 兩個普通版模型價格相同:

| resolution | USD/張 |
| ---------- | ----: |
| 1K         | 0.015 |
| 2K         | 0.020 |
| 4K         | 0.025 |

這三個價格均適用於 `low`, `medium`, `high`, `xhigh`, `max`. 當前參考圖輸入沒有額外的按張費用. 賬戶專屬定價或折扣可能不同, 最新價格以 [模型定價頁](https://toapis.com/pricing) 和賬戶實際配置為準.

## 與 VIP 版的區別

| 項目         | 普通版                    | VIP 版                  |
| ---------- | ---------------------- | ---------------------- |
| 模型名        | 不帶 `-vip`              | 帶 `-vip`               |
| 任務模式       | 異步任務, 通過任務 ID 查詢圖片 URL | 異步任務, 通過任務 ID 查詢圖片 URL |
| size       | 推薦比例, 如 `16:9`         | 像素尺寸, 如 `1536x1024`    |
| resolution | `1K`, `2K`, `4K`       | 省略, 由 size 表達尺寸        |
| 計費         | 按 resolution 對應的每張價格   | 按實際文本和圖片 token         |
| 參考圖        | 生成接口中填寫參考圖 URL         | 編輯接口上傳圖片文件             |

切換到 VIP 時, 請同時調整模型名和參數. 詳見 [GPT-Image-2.5 VIP](../gpt-image-2.5-vip/generation).