GPT-Image-2.5 图像生成 | ToAPIs Documentation

POST

/v1/images/generations

普通版通过 POST /v1/images/generations 创建图片任务, 返回任务 ID. 任务完成后通过查询接口获取图片 URL. 两个模型使用相同的请求格式:

模型	请求中的 model
Flare	`gpt-image-2.5-flare`
Sunburst	`gpt-image-2.5-sunburst`

gpt-image-2.5 是系列名称. 调用时请填写表中的完整模型名.

中国大陆用户可将示例中的 https://api.toapis.com 替换为 https://api.toapis.cn. API Key 可在控制台创建.

快速开始

将自己的 ToAPIs API Key 设置为环境变量 TOAPIS_API_KEY, 提交任务:

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",
    "prompt": "儿童绘本风格, 一位兽医用听诊器给小水獭检查心跳",
    "quality": "high",
    "size": "1:1",
    "resolution": "1K",
    "n": 1
  }'

提交响应示例:

{
  "id": "tsk_img_example",
  "object": "generation.task",
  "model": "gpt-image-2.5-flare",
  "status": "pending",
  "progress": 0,
  "created_at": 1788951900,
  "metadata": {}
}

保存返回的 id, 将下方的 TASK_ID 替换为该值后查询:

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. 建议每隔数秒查询一次. 完整字段见图片任务状态接口.

提交成功表示任务已创建. 请等到 completed 后再下载图片; 等待期间继续查询同一个任务 ID.

请求参数

Authorizationstring请求头必填

使用 Bearer YOUR_TOAPIS_API_KEY 认证.

modelstring请求体必填

gpt-image-2.5-flare 或 gpt-image-2.5-sunburst.

promptstring请求体必填

图片描述. 使用参考图时, 描述需要保留的主体和需要修改的内容.

qualitystring请求体默认值: high

当前普通版固定使用 high, 可省略此参数. 传入其他字符串值会被忽略, 统一使用 high. Playground 不展示质量选项.

当前普通版按 resolution 定价.

sizestring请求体默认值: 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 让上游自动选择尺寸, 但最终宽高比和像素尺寸无法保证.

resolutionstring请求体默认值: 1K

分辨率档位, 支持 1K, 2K, 4K, 也接受小写形式. 该字段决定普通版的计价档位.

backgroundstring请求体

可选的背景参数. 传入 "transparent" 生成透明背景图片, 不传此参数时正常生图.

文生图和带 reference_images 的图生图均可使用. 普通生图请直接省略此字段.

ninteger请求体默认值: 1

每次请求使用 1, 生成一张图片.

reference_imagesstring[]请求体

可选的参考图 URL 列表, 用于图生图. 图片地址需要能被服务端访问. 本接口只支持图片 URL, 不支持本地文件上传或 base64; 本地图片请先通过上传图片接口获取 URL.

也兼容 image_urls. 选择其中一个字段即可.

透明背景

生成请求中加入 "background": "transparent" 即可得到透明背景的图片. 不传该字段时正常生图.

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",
    "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, 返回值仍然是异步任务:

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",
    "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. 当前参考图输入没有额外的按张费用. 账户专属定价或折扣可能不同, 最新价格以模型定价页和账户实际配置为准.