> ## 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 文檔](https://docs.toapis.com/docs/zh-Hant/api-reference/images/gpt-image-2.5-vip/generation.md). 兩版都使用異步任務, 主要區別在 size 格式和計價方式.

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

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`. 建議每隔數秒查詢一次. 完整字段見 [圖片任務狀態接口](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` 或 `gpt-image-2.5-sunburst`.

**prompt** `string` *required*

圖片描述. 使用參考圖時, 描述需要保留的主體和需要修改的內容.

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

當前普通版固定使用 `high`, 可省略此參數. 傳入其他字符串值會被忽略, 統一使用 `high`. Playground 不展示質量選項.

當前普通版按 resolution 定價.

**size** `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 版的像素尺寸寫法不同.

也可以傳 `auto` 讓上游自動選擇尺寸, 但最終寬高比和像素尺寸無法保證.

**resolution** `string` (default: 1K)

分辨率檔位, 支持 `1K`, `2K`, `4K`, 也接受小寫形式. 該字段決定普通版的計價檔位.

**background** `string`

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

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

**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`. 選擇其中一個字段即可.

## 透明背景

生成請求中加入 `"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](https://docs.toapis.com/docs/zh-Hant/api-reference/images/gpt-image-2.5-vip/generation.md).


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