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

> gpt-image-2.6-flare 和 gpt-image-2.6-sunburst 普通版接入指南, 包含非同步任務, 三檔品質, 參考圖, GIF 和 SVG 輸出, 按解析度計價

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

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

`gpt-image-2.6` 是系列名稱. 呼叫時請填寫表中的完整模型名.

> [!NOTE]
>
> **中國大陸用戶請注意:** 請使用 `https://api.toapis.cn` 作為 API 端點 (Base URL), 將本文範例中的 `https://api.toapis.com` 替換為 `https://api.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://api.toapis.com/v1/images/generations \
  --header "Authorization: Bearer $TOAPIS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2.6-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.6-flare",
  "status": "pending",
  "progress": 0,
  "created_at": 1788951900,
  "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, `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.6-flare` 或 `gpt-image-2.6-sunburst`.

**prompt** `string` *required*

圖像描述. 使用參考圖時, 請說明要保留的主體和要修改的內容.

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

三檔品質: `low`, `medium`, `high`. Playground 預設 `high`. 不傳時使用上游預設值.

**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`.

建議將 `size` 設為畫面比例並明確傳入 `resolution`, 服務會按兩者計算輸出像素尺寸.

也可以傳 `auto` 讓上游自行決定尺寸, 但最終比例和像素尺寸不作保證.

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

解析度檔位. 支援 `1K`, `2K`, `4K`, 小寫同樣有效. 普通版按該欄位計價.

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

每次請求傳 `1`, 生成一張圖.

**background** `string`

可選背景設定. 傳 `"transparent"` 生成透明背景圖片, 普通生成不傳該欄位.

文生圖和攜帶 `reference_images` 的請求皆可使用.

**output\_format** `string`

輸出格式: `png`, `jpeg`, `webp`, `gif`, `svg`. 不傳時使用上游預設格式. GIF 和 SVG 的附加參數與限制見下文對應章節.

**frame\_count** `integer` (default: 9)

僅 GIF 生效. 幀數, 取值 `2` 到 `64`. 文生 GIF 按該值生成; 圖生 GIF 固定輸出 `9` 幀.

**frame\_duration\_ms** `integer` (default: 200)

僅 GIF 生效. 單幀時長, 毫秒, 取值 `20` 到 `2000`, 步長 `10`.

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

可選參考圖 URL 列表, 最多 10 張. 圖片必須可被服務端存取, 僅支援 URL, 不接受本地檔案和 base64. 本地圖片請先透過 [上傳圖片接口](https://docs.toapis.com/docs/zh-Hant/api-reference/uploads/images.md) 取得 URL.

同樣支援 `image_urls` 欄位, 兩者選其一.

與 `"output_format": "gif"` 組合時即為圖生 GIF.

## 透明背景

在生成請求中加入 `"background": "transparent"` 即可獲得透明背景圖片, 普通生成不傳該欄位.

```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.6-flare",
    "prompt": "透明背景上的紅色圓形貼紙",
    "quality": "high",
    "size": "1:1",
    "resolution": "1K",
    "background": "transparent",
    "n": 1
  }'
```

任務按任務 ID 正常查詢, 從 `result.data` 讀取圖片 URL.

## GIF 輸出

將 `output_format` 設為 `gif` 生成動圖. `frame_count` 控制幀數 (`2` 到 `64`, 預設 `9`), `frame_duration_ms` 控制單幀時長 (`20` 到 `2000` 毫秒, 步長 `10`, 預設 `200`).

```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.6-flare",
    "prompt": "扁平插畫風格, 一架紙飛機在藍天中循環飛行",
    "output_format": "gif",
    "frame_count": 8,
    "frame_duration_ms": 200,
    "size": "1:1",
    "n": 1
  }'
```

### 圖生 GIF

加入 `reference_images` 即可讓已有圖片動起來. 圖生 GIF 固定輸出 `9` 幀, `frame_count` 在該模式下不生效, `frame_duration_ms` 仍然有效.

```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.6-flare",
    "prompt": "讓畫面中的場景輕輕動起來",
    "reference_images": ["https://example.com/scene.png"],
    "output_format": "gif",
    "frame_duration_ms": 200,
    "n": 1
  }'
```

## SVG 輸出

將 `output_format` 設為 `svg` 生成向量圖, 無需其他附加欄位.

```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.6-flare",
    "prompt": "極簡風格的雪山標誌, 扁平向量風",
    "output_format": "svg",
    "n": 1
  }'
```

## 比例與解析度對照

| 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`, 最多 10 張. 下面範例使用 Sunburst, 同樣回傳非同步任務:

```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.6-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 查詢結果.

## 計費

普通版按生成的每張圖片計費, 價格檔位由 `resolution` 決定. GIF 和 SVG 輸出按相同的單圖價格計費. 參考圖輸入暫不額外收費. 帳號專屬定價或折扣可能不同, 最新價格以 [模型定價頁](https://toapis.com/pricing) 和帳戶配置為準.

## 相關模型

[GPT-Image-2.6 Official](https://docs.toapis.com/docs/zh-Hant/api-reference/images/gpt-image-2.6-official/generation.md) 版走官接渠道, 提供六檔品質, 自訂像素尺寸, 標注引導編輯和按 token 計費. 使用該渠道請傳帶 `-official` 後綴的模型名.


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