GPT Image 2.5
用提示词生成 1–4 张图片，可以带参考图，五档质量，可以出透明背景，按张计费。
GPT Image 2.5（产品 gpt_image）用提示词生成图片，可以带最多 16 张参考图。有两个版本（flare、sunburst）和五档质量，可以出透明背景的图片。一个任务出 1–4 张，按质量和分辨率按张计费。
创建任务
https://api.nanoapi.ai/v1/tasks用所有模型共用的创建任务接口，model 传 "gpt-image-2.5"。接口通常不到 1 秒返回，几秒内按 num_outputs 张冻结费用；任务结束后获取结果。
请求头
| 请求头 | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <API Key>，见鉴权 |
Content-Type | 是 | application/json |
Idempotency-Key | 否 | 每个新任务一个唯一字符串，建议用 UUID（1–255 个字符），见防止重复创建 |
请求体
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | gpt-image-2.5 |
prompt | string | 是 | 描述要生成的图片，最长 8000 字符。引用参考图写 @Image1、@Image2…，见在提示词里引用图片 |
image_urls | string[] | 否 | 参考图，最多 16 张；不传就是只用提示词生成。见素材 |
variant | string | 是 | flare 或 sunburst，参数和价格完全一样。flare 速度快，适合日常创作和批量出图；sunburst 细节更精准，适合精修和高质量成片，生成稍慢（见耗时参考） |
quality | string | 是 | low、medium、high、xhigh 或 max，决定价格 |
resolution | string | 是 | 1k、2k 或 4k，决定价格 |
aspect_ratio | string | 是 | auto、1:1、3:2、2:3、4:3、3:4、16:9、9:16、21:9、27:16、16:27、9:8、8:9、4:5 或 5:4。auto：有参考图时跟随第一张参考图的比例，没有时按 1:1 |
background | string | 否 | auto、opaque 或 transparent。不传、auto、opaque 都出不透明背景；要透明背景必须传 transparent（带参考图也支持），出带透明通道的 PNG。只在提示词里写「透明背景」不行：模型会把灰白棋盘格画进画面，看起来像透明，其实不透明 |
num_outputs | integer | 是 | 出几张，1–4。按这个张数冻结，只按生成出来的张数扣费，见价格 |
webhook_url | string | 否 | 任务成功或失败时通知该地址：https，最长 2048 字符，不能指向内网、回环或保留地址。见回调 |
传了其他参数（例如别的图片模型才有的 seed、remove_bg）返回 400 invalid_request，见错误。
用 1 张参考图生成 2 张方形的产品图，medium 质量、2k：
curl https://api.nanoapi.ai/v1/tasks \
-H "Authorization: Bearer $NANOAPI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 2a7e9c41-5b3d-4e8f-a06c-1d9b7f4e3a25" \
-d '{
"model": "gpt-image-2.5",
"prompt": "Place the product from @Image1 on a marble table, studio lighting",
"image_urls": ["https://example.com/product.png"],
"variant": "sunburst",
"quality": "medium",
"resolution": "2k",
"aspect_ratio": "1:1",
"num_outputs": 2
}'响应：200 OK。data 是刚创建的任务，只有下面这几个字段，各字段的含义见创建任务的返回。保存 data.id，用它获取结果。任务创建后仍可能失败（例如余额不够这次的费用），以查询或回调的结果为准。
{
"code": 200,
"message": "success",
"data": {
"object": "task",
"id": "tk_01jbh5p8d3y6w9c4n7r0x2f5t8",
"model": "gpt-image-2.5",
"status": "queued",
"error": null,
"created_at": "2026-11-01T08:30:00Z"
}
}获取结果
耗时仅供参考（开始生成到出图，不含排队，另加几秒转存；上游忙时会更慢），flare 依次为 1k / 2k / 4k：low 12 / 16 / 22 秒，medium 16 / 21 / 25 秒，high 25–30 / 32 / 35 秒，xhigh 37 / 41 / 50 秒，max 69 / 71 / 87 秒。sunburst 更慢：medium 1k 约 20 秒，high 1k 约 46 秒。同一个任务的多张图并行生成，出多张的总耗时和单张差不多。任务结束（成功或失败）后用下面任一方式拿结果：
- 回调（生产环境推荐）：创建时传了
webhook_url，任务结束时会把完整的任务推送一次，见回调。 - 轮询：用
data.id调用GET /v1/tasks/{task_id}，间隔 15 秒以上，直到status为succeeded或failed；多个任务用列出任务的ids一次查询。
上面的请求成功后（省略了其他字段）：
{
"status": "succeeded",
"input": {
"prompt": "Place the product from @Image1 on a marble table, studio lighting",
"image_urls": ["https://example.com/product.png"],
"variant": "sunburst",
"quality": "medium",
"resolution": "2k",
"aspect_ratio": "1:1"
},
"num_outputs": 2,
"outputs": [
{
"index": 0,
"type": "image",
"url": "https://cdn.nanoapi.ai/h/tk_01jbh5p8d3y6w9c4n7r0x2f5t8_1_1793521800.png",
"preview_url": "https://cdn.nanoapi.ai/h/tk_01jbh5p8d3y6w9c4n7r0x2f5t8_1_1793521800_compressed.jpg"
},
{
"index": 1,
"type": "image",
"url": "https://cdn.nanoapi.ai/h/tk_01jbh5p8d3y6w9c4n7r0x2f5t8_2_1793521800.png",
"preview_url": "https://cdn.nanoapi.ai/h/tk_01jbh5p8d3y6w9c4n7r0x2f5t8_2_1793521800_compressed.jpg"
}
],
"billing": {
"currency": "USD",
"frozen": "…", // 2 × medium 2k 的每张单价
"charged": "…", // 一样：2 张都生成出来了
"refunded": "0.00",
"billed_seconds": null
}
}| 字段 | GPT Image 2.5 |
|---|---|
outputs | 每张生成出来的图片一项，最多 num_outputs 项 |
outputs[].type | image |
outputs[].url | PNG 原图；传了 background: "transparent" 时保留透明背景。用于下载或查看大图；文件较大（1k 约 1–2 MB，4k 约 30 MB） |
outputs[].preview_url | JPEG 预览图，长边不超过 1024（小图不放大），透明背景铺成白底，列表、缩略图请用它。生成不了预览图时为 null |
billing.billed_seconds | 一直是 null：图片按张计费 |
input | 你传的参数；可选的 image_urls、background 传了才有 |
失败时冻结的钱全额退回，原因在 data.error.type，见错误。完整的字段见任务对象。
出图尺寸
宽×高（像素），quality、variant 不影响尺寸。4k 的总像素上限约 830 万，所以 4k 的 1:1 是 2880×2880，不是 4096×4096。auto 的尺寸取决于参考图，不在表里。
aspect_ratio | 1k | 2k | 4k |
|---|---|---|---|
1:1 | 1024×1024 | 2048×2048 | 2880×2880 |
3:2 | 1024×688 | 2048×1360 | 3504×2336 |
2:3 | 688×1024 | 1360×2048 | 2336×3504 |
4:3 | 1168×880 | 2336×1744 | 3312×2480 |
3:4 | 880×1168 | 1744×2336 | 2480×3312 |
5:4 | 1120×896 | 2240×1792 | 3200×2560 |
4:5 | 896×1120 | 1792×2240 | 2560×3200 |
9:8 | 1008×896 | 2160×1920 | 3024×2688 |
8:9 | 896×1008 | 1920×2160 | 2688×3024 |
16:9 | 1344×752 | 2688×1520 | 3840×2160 |
9:16 | 752×1344 | 1520×2688 | 2160×3840 |
27:16 | 1296×768 | 2592×1536 | 3456×2048 |
16:27 | 768×1296 | 1536×2592 | 2048×3456 |
21:9 | 1344×576 | 2688×1152 | 3840×1648 |
张数比请求的少
每张图单独生成。有几张没生成出来（例如被内容审核拦下）时，任务仍是 succeeded，outputs 里只有生成出来的那几张，比 num_outputs 少。只按这几张扣费，冻结的其余部分退回（billing.refunded）。一张都没生成出来时任务才是 failed，冻结的钱全额退回：其中只要有 1 张是被内容审核拦下的，失败原因就是 content_policy（不一定每张都被拦，其余几张可能是别的原因），否则一般是 generation_failed。outputs[].index 按生成出来的那几张从 0 连续编号，张数比请求的少时不对应请求里的第几张，不要按它去对位。
素材
参考图以公开的 http(s) 链接放在 image_urls 里提交。不提供上传接口，请自行托管文件。链接最长 4096 字符，必须能直接下载，不能指向 localhost 或内网、回环、保留地址。
参考图（image_urls） | |
|---|---|
| 数量 | 0–16 张（GET /v1/products 的 limits.max_reference_images） |
| 格式 | JPEG、PNG、WebP、AVIF、GIF（取第一帧）、BMP、TIFF。不支持 HEIC / HEIF：iPhone 照片默认是 HEIC，请先转成 JPEG |
| 透明背景 | 透明背景的 PNG 会铺成白底再使用 |
| 有问题时 | 生成时才读取，这时已经冻结过费用：下载不了、格式不支持时任务失败（invalid_media），冻结的钱全额退回 |
任务结束前所有链接都要保持可访问，有有效期的链接也不能提前过期。
在提示词里引用图片
prompt 里写 | 指代 |
|---|---|
@Image1、@Image2… | image_urls 里的图片，按顺序编号 |
- 引用超出了传入的张数（例如只传了 1 张却写了
@Image2，或者没传image_urls却写了@Image）：返回400 invalid_request，param为"prompt"，任务不会创建。 @前面是字母、数字或点的不算引用，所以提示词里写邮箱（例如bob@image2go.com）没有问题。
价格
冻结 = 所选质量和分辨率的每张单价 × num_outputs
扣费 = 所选质量和分辨率的每张单价 × 生成出来的张数正在读取当前价格…
- 只有
quality和resolution影响价格；variant、background、aspect_ratio和参考图都不影响。 - 创建后几秒内按
num_outputs张冻结。成功后按生成出来的张数扣费，其余退回，见张数比请求的少；失败全额退回。
例如上面的请求（medium、2k，num_outputs 为 2）冻结 2 × medium 2k 的每张单价，2 张都生成出来时扣同样的金额；只生成出 1 张时扣 1 × 这个单价，另一张的钱退回。冻结和扣费的通用规则见计费。
价格只看请求就能算出来，可以在提交前显示：用 GET /v1/products 返回的当前单价计算（prices 里每个 quality 和分辨率一行）。价格会调整，不要写死；实际费用以查询任务返回的 billing.frozen 为准。
错误
这个模型特有的错误和失败原因。创建任务的全部错误见创建任务 → 错误，全部失败原因见失败原因。
创建请求出错：请求返回 HTTP 错误，任务不会创建。param 是对应的参数名。
| 状态码 | error.type | 何时出现 | 怎么处理 |
|---|---|---|---|
400 | invalid_request | 少传了必填参数（Field required，param 是缺的那个），或者 prompt 是空的（prompt is required） | 必填参数都要传，见创建任务 |
400 | invalid_request | 提示词引用了没传的图片，param 为 "prompt"（例如 prompt references @Image2, but image_urls has 1 image: use @Image1） | 改正引用，或者把图片加进 image_urls |
400 | invalid_request | variant、quality、resolution、aspect_ratio、background 不是上面列出的值（例如 Input should be 'low', 'medium', 'high', 'xhigh' or 'max' for gpt-image-2.5），num_outputs 不是 1–4，或者 image_urls 超过 16 张 | 改成允许的值 |
400 | invalid_request | 传了这个模型没有的参数：别的图片模型的参数（thinking_level、enable_web_search、enable_image_search、seed、remove_bg）或视频模型的参数（Extra inputs are not permitted） | 去掉这个参数 |
创建接口的其他错误（401、402、429 等）见创建任务 → 错误。
任务失败：创建请求成功（200），任务之后变成 failed。这种情况没有 HTTP 状态码，原因在任务的 error.type，通过查询任务或回调拿到。
error.type | 何时出现 | 怎么处理 |
|---|---|---|
insufficient_balance | 可用余额不够 num_outputs × 每张单价。创建后几秒内出现，不冻结费用 | 充值，或者少出几张、降低质量，再重新创建 |
spend_limit_exceeded | 加上这个任务的费用会超出 Key 的消费限额。创建后几秒内出现，不冻结费用 | 在控制台 → API Keys 调高限额，或者等限额重置后重新创建 |
invalid_media | 参考图下载不了或读不了（例如 HEIC 照片、文件损坏）。生成时才发现，这时已经冻结过费用，全额退回 | 按 error.message 换掉那张图（HEIC 先转成 JPEG），重新创建 |
content_policy | 一张图都没生成出来，并且至少 1 张是因为提示词或参考图不符合内容政策被拦下的（不一定每张都被拦）。只有部分张被拦下时任务仍然成功，返回其余的张，见张数比请求的少 | 原样重新提交还会失败，请更换提示词或图片 |
generation_failed | 一张图都没生成出来 | 稍后重新创建，或者换一份提示词、图片 |
queue_timeout / internal_error | 排队超过 30 分钟未开始 / 内部错误 | 稍后重新创建 |
所有失败的任务都已全额退回冻结金额，billing.charged 为 "0.00"。