> ## 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 官方渠道 圖像生成

> Sunburst 和 Flare 官方渠道的非同步圖片任務, R2 結果與官方 8 折 token 計費

透過 Azure 官方渠道呼叫兩個 GPT-Image-2.5 型號. 提交後立即回傳非同步任務 ID, 背景生成圖片並將結果轉存至 R2.

| 型號                | model                             |
| ----------------- | --------------------------------- |
| Sunburst Official | `gpt-image-2.5-sunburst-official` |
| Flare Official    | `gpt-image-2.5-flare-official`    |

呼叫時必須使用表中的完整模型名稱. `gpt-image-2.5-official` 只是系列名稱, 不能作為請求的 model.

中國大陸使用者可將範例中的 `https://api.toapis.com` 替換為 `https://api.toapis.cn`. 在 [控制台](https://toapis.com/console/token) 建立 API Key, 並設定環境變數 `TOAPIS_API_KEY`.

## 提交與查詢

提交一張 Flare 圖片. 呼叫 Sunburst 時替換 model 即可:

```bash theme={null}
curl --fail-with-body --request POST \
  --url https://api.toapis.com/v1/images/generations \
  --header "Authorization: Bearer $TOAPIS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2.5-flare-official",
    "prompt": "A small blue circle on a plain white background",
    "quality": "low",
    "size": "1024x1024",
    "n": 1
  }'
```

```json theme={null}
{
  "id": "tsk_img_example",
  "object": "generation.task",
  "model": "gpt-image-2.5-flare-official",
  "status": "pending",
  "progress": 0,
  "created_at": 1789099098,
  "metadata": {}
}
```

儲存提交回應的 `id`, 將下方 `TASK_ID` 替換為該值:

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

提交回應為 `pending`. 查詢時可能看到 `queued` 或 `in_progress`, 最終為 `completed` 或 `failed`. `completed` 時從 `result.data[].url` 取得已轉存 R2 的圖片 URL, `failed` 時讀取 `error`. 建議每隔數秒查詢同一個任務 ID; 高品質生成可能需要數分鐘, 等待期間請勿重複提交. 完整欄位見 [圖片任務狀態介面](../../tasks/image-status).

## 請求參數

<ParamField header="Authorization" type="string" required>
  使用 ToAPIs API Key, 格式為 `Bearer YOUR_API_KEY`. 無需提供 Azure 憑證.
</ParamField>

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

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

<ParamField body="quality" type="string" default="high">
  支援 `low`, `medium`, `high`, `xhigh`, `max` 五檔. 品質和尺寸會影響實際 token 用量與耗時.
</ParamField>

<ParamField body="size" type="string" default="1024x1024">
  使用像素尺寸, 例如 `1024x1024`, `1536x1024` 或 `1024x1536`. 自訂尺寸須符合上游驗證. 以下範例不需要額外傳入 resolution.
</ParamField>

<ParamField body="background" type="string">
  可選. 傳入 `transparent` 請求透明背景, 省略時使用上游預設背景. 預設 PNG 輸出可保留透明通道.
</ParamField>

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

## 參考圖 URL

需要圖生圖時, 在同一個 JSON 生成請求中加入 `image_urls`. URL 必須可由伺服器存取. 可先使用 [圖片上傳介面](../../uploads/images) 取得 URL. 參考圖產生圖片輸入 token 費用, 提交與查詢仍使用同一套非同步流程.

```bash theme={null}
curl --fail-with-body --request POST \
  --url https://api.toapis.com/v1/images/generations \
  --header "Authorization: Bearer $TOAPIS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2.5-sunburst-official",
    "prompt": "Keep the subject and replace the background with a snowy forest",
    "image_urls": ["https://example.com/reference.png"],
    "quality": "high",
    "size": "1024x1024",
    "n": 1
  }'
```

## token 價格

2026-09-11 核對的標準售價如下. 兩個 official 型號均按官方 token 價格的 80% 計費, 即官方 8 折:

| 類型     | USD / 1,000,000 tokens |
| ------ | ---------------------: |
| 文字輸入   |                   4.00 |
| 快取文字輸入 |                   1.00 |
| 圖片輸入   |                   6.40 |
| 快取圖片輸入 |                   1.60 |
| 圖片輸出   |                  24.00 |

提交時先預扣額度, 成功後按上游實際文字和圖片 token 用量多退少補. 五檔品質共用上述單價, 沒有按品質固定的每張價格. 呼叫前需要足夠的帳戶餘額和 API Key 額度.

費用公式, 單位為 USD:

```text theme={null}
USD = (
  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
```

例如一次請求使用 17 個未快取文字輸入 tokens 和 196 個圖片輸出 tokens, 費用為 `(17 * 4 + 196 * 24) / 1,000,000 = $0.004772`. 這不是每張圖片的固定價格.

帳戶專屬定價或折扣繼續適用. 最終扣費可在使用日誌中核對, 最新售價以 [定價頁](https://toapis.com/pricing) 和帳戶設定為準.

## 相關型號

[普通版](../gpt-image-2.5/generation) 和 [VIP 版](../gpt-image-2.5-vip/generation) 使用各自的完整模型名稱. 呼叫本頁官方渠道時請使用 `-official` 後綴.