> ## 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` 是系列名称. 调用时请填写表中的完整模型名.

中国大陆用户可将示例中的 `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/cn/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/cn/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/cn/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.