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

> Sunburst 和 Flare 官方渠道的异步图片任务, 支持标注编辑, GIF 和 SVG 输出, R2 结果和 token 计费

通过官方渠道调用两个 GPT-Image-2.6 型号. 提交后立即返回异步任务 ID, 后台生成图片并将结果转存到 R2.

| 型号 | model |
| - | - |
| Sunburst Official | `gpt-image-2.6-sunburst-official` |
| Flare Official | `gpt-image-2.6-flare-official` |

调用时必须使用表中的完整模型名. `gpt-image-2.6-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.6-flare-official",
    "prompt": "A small blue circle on a plain white background",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'
```

```json theme={null}
{
  "id": "tsk_img_example",
  "object": "generation.task",
  "model": "gpt-image-2.6-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; 高质量生成可能需要数分钟, 等待期间不要重复提交. 完整字段见 [图片任务状态接口](https://docs.toapis.com/docs/cn/api-reference/tasks/image-status.md).

## 请求参数

**Authorization** `string` *required*

使用 ToAPIs API Key, 格式为 `Bearer YOUR_API_KEY`.

**model** `string` *required*

`gpt-image-2.6-sunburst-official` / `gpt-image-2.6-flare-official`.

**prompt** `string` *required*

图片描述. 使用参考图或标注图时描述希望保留和修改的内容.

**size** `string` (default: auto)

支持比例名 (如 `1:1`, `3:2`, `2:3`, `16:9`, `9:16`) 或像素尺寸 (如 `1024x1024`, `1536x1024`). GIF 输出时 size 语义以 GIF 节为准. 像素尺寸两边须为 16 的倍数且不小于 16, 单边不超过 3840, 长短边比不超过 3:1; 超过 2560x1440 属于实验尺寸.

**resolution** `string`

分辨率档位 `1k` / `2k` / `4k`. 显式传入时优先于按 size 推断的档位. 档位影响实际 token 用量与耗时.

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

支持 `auto`, `low`, `medium`, `high`, `xhigh`, `max` 六档. `auto` 表示由模型为每个请求自动选择质量档位. 质量影响实际 token 用量与耗时.

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

每次请求生成 1 到 4 张. `output_format` 为 `svg` 时仅支持 `1`.

**output\_format** `string`

输出格式 `png` / `jpeg` / `webp` / `gif` / `svg`. 省略时使用上游默认格式. `gif` 和 `svg` 的附加参数与约束见下方对应小节.

**output\_compression** `integer`

0-100 的压缩率, 仅 `jpeg` 和 `webp` 输出有效.

**background** `string`

`transparent` / `opaque` / `auto`. 显式透明仅适用 `png` / `webp` 输出; `svg` 默认透明.

**moderation** `string`

内容审核级别 `auto` / `low`.

**complexity** `string`

生成复杂度 `low` / `medium` / `high`, 省略时默认 `high`. 不单独收费.

## 参考图与遮罩

需要图生图时在同一个 JSON 请求中添加 `image_urls`, 最多 16 张, URL 必须可由服务端访问. 可先使用 [图片上传接口](https://docs.toapis.com/docs/cn/api-reference/uploads/images.md) 获取 URL. 参考图产生图片输入 token 费用.

`mask_url` 指向一张 PNG alpha 遮罩图, 尺寸需与第一张参考图一致, 必须配合 `image_urls` 使用.

```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-official",
    "prompt": "Keep the subject and replace the masked area with a snowy forest",
    "image_urls": ["https://example.com/reference.png"],
    "mask_url": "https://example.com/mask.png",
    "quality": "high",
    "size": "1024x1024",
    "n": 1
  }'
```

## 标注编辑

`markup_url` 指向一张带标注的参考图 (或直接用 `markup` 传内联标注对象), 配合 `image_urls` 提供原图, 模型按标注语义编辑. `markup_url` 与 `mask_url` 互斥, 一次请求只能用一种.

```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-official",
    "prompt": "Follow the markup annotations to adjust the layout",
    "image_urls": ["https://example.com/reference.png"],
    "markup_url": "https://example.com/markup.png",
    "quality": "high",
    "n": 1
  }'
```

## GIF 输出

`output_format` 传 `gif` 生成动图, 用 `frame_count` 指定帧数 (2-16), `frame_duration_ms` 指定每帧时长. GIF 仅支持文生图, 不能同时使用 `image_urls`, `mask_url`, `markup_url`, `markup` 或 `output_compression`. `size` 须传精确像素尺寸 (如 `512x512`) 或省略以使用上游默认帧尺寸; `1:1` 等比例值在 GIF 下会被上游拒绝.

```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-official",
    "prompt": "A paper airplane looping across a blue sky, flat illustration",
    "output_format": "gif",
    "frame_count": 8,
    "frame_duration_ms": 200,
    "size": "512x512",
    "n": 1
  }'
```

## SVG 输出

`output_format` 传 `svg` 生成矢量图, 需同时提供 `svg` 对象并在其中指定 `svg.model`. SVG 仅支持文生图, `n` 只能为 `1`, 不能同时使用 `image_urls`, `mask_url`, `markup_url`, `markup` 或 `output_compression`. 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-official",
    "prompt": "A minimalist mountain logo, flat vector style",
    "output_format": "svg",
    "svg": { "model": "gpt-5" },
    "n": 1
  }'
```

## token 价格

两个 official 型号按 token 分项计费: 文本输入, 缓存文本输入, 图片输入, 缓存图片输入和图片输出分别计价. 提交时先预扣额度, 成功后按实际 token 用量多退少补.

费用公式, 单位为 USD:

```text theme={null}
USD = (
  uncached_text_input_tokens * text_input_price
  + cached_text_input_tokens * cached_text_input_price
  + uncached_image_input_tokens * image_input_price
  + cached_image_input_tokens * cached_image_input_price
  + image_output_tokens * image_output_price
) / 1,000,000
```

GIF 按整段动画的输出 token 计费. SVG 输出除图片 token 外, 还会按 `svg.model` 指定的文本模型产生一次文本输入/输出 token 费用.

账户专属定价或折扣继续适用. 最终扣费可在使用日志中核对, 最新售价以 [定价页](https://toapis.com/pricing) 和账户配置为准.

## 相关型号

[GPT-Image-2.5 官方渠道](https://docs.toapis.com/docs/cn/api-reference/images/gpt-image-2.5-official/generation.md), [普通版](https://docs.toapis.com/docs/cn/api-reference/images/gpt-image-2.5/generation.md) 和 [VIP 版](../gpt-image-2.5-vip/generation) 使用各自的完整模型名. 调用本页官方渠道时请使用 `-official` 后缀.


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