GPT Image 系列

OpenAI 的图像生成模型，共三款：gpt-image-2.5-flare、gpt-image-2.5-sunburst、gpt-image-2，都通过 OpenAI 兼容接口调用。

本系列文档的结论均来自实测接口，代码示例都原样运行通过。最近校验：2026-09-30。

我要做什么

文生图用一段文字生成图片。改图与多图上传一张或多张图片，按文字要求修改或融合。局部重绘用 mask 圈出区域，只重画这一块。用你自己的工具生图不写代码。Cherry Studio、LobeHub 填几项配置，Claude Code、Codex 复制一段提示词。

三个接口共用的请求结构和响应字段，见 Images API。

选哪个模型

要点文生图选 gpt-image-2.5-flare，改图选 gpt-image-2.5-sunburst。

gpt-image-2.5-flare文生图首选

日常批量生成，出图快
6 档画质：low 至 max

Azure · OpenAI

gpt-image-2.5-sunburst改图首选

改图、多图融合，还原度优先
6 档画质：low 至 max

Azure · OpenAI

gpt-image-2上一代

已有项目可继续使用
4 档画质，无 xhigh、max

Azure · OpenAI

从 gpt-image-2 换到 2.5 时，需要重新选择画质档位，见下方画质与价格。两家供应商都支持文生图和改图，网关会自动路由。

模型 ID（调用时原样复制）

文生图openai/gpt-image-2.5-flare日常批量生成，出图快

改图openai/gpt-image-2.5-sunburst改图、多图融合，还原度优先

上一代openai/gpt-image-2没有 xhigh、max 两档

画质（quality）与价格

要点显式传 quality，开发阶段先用 low。不传不等于 medium。

quality 对价格影响最大，档位越高越贵、越慢。

OpenAI 官方参考价（每张，只算输出图片，不含提示词和参考图）：

档位	`gpt-image-2` · 1024×1024	`gpt-image-2` · 1024×1536 或 1536×1024
`low`	$0.006	$0.005
`medium`	$0.053	$0.041
`high`	$0.211	$0.165

2.5 两款官方没有给每张价格表，给的是单价：输出图片每百万 token $30，参考图输入每百万 token $8，文字输入每百万 token $5。官方算例：1024×1024 的 low 档输出 196 个 token，约 $0.00588。其他档位和尺寸可以用官方计算器估算。

以上是 OpenAI 官方数据，实际扣费以响应里的 usage 为准。OfoxAI 实时价格（含折扣）见模型页。

各模型支持的档位：

档位	2.5（flare、sunburst）	`gpt-image-2`
`low` / `medium` / `high`	支持	支持
`xhigh` / `max` 仅 2.5	支持	不支持，返回 400
`auto` 或不传易错	模型自己选，不等于 `medium`，建议显式指定	同左

不支持 standard 和 hd（DALL·E 的旧取值），传入会返回 400。

耗时与超时（timeout）

要点将客户端超时设置为 600 秒。

接口为同步调用，图片生成完成后才返回响应。客户端提前断开连接将无法获取图片，但该请求仍会计费。

发送请求生成中，可能需要数分钟返回图片

60 / 120 秒 常见默认超时，生成途中就会断开，图片丢失但仍计费

600 秒 推荐设置，能等到图片返回

生成耗时随模型、画质和尺寸变化，高画质、大尺寸及改图请求可能需要数分钟，常见的 60 秒或 120 秒默认超时不足以覆盖。

尺寸（size）

要点宽、高都是 16 的倍数，且总像素不低于 655,360。

size 可以自定义宽高，格式为 宽x高，但必须同时满足以下四条，任何一条不满足都返回 400。

16 的倍数

宽、高都能被 16 整除

✗ 1000x1000

最长边 ≤ 3840

任一边都不超过 3840

✗ 4096x4096

宽高比 ≤ 3:1

宽高比在 1:3 到 3:1 之间

✗ 3200x1024

像素 ≥ 655,360易错

总像素不低于 655,360

✗ 768x768 → ✓ 1024x768

不传或传 auto 易错：由模型决定尺寸，不保证是 1024×1024，也不保证和参考图一致。实测文生图和改图都返回了 1254×1254。需要固定尺寸时，请显式传入。

官方标注的上限是 3840×2160，超过 2560×1440 属于实验性分辨率。

技术规格

项目	规格
返回方式	同步返回，图片是 `data[0].b64_json` 里的纯 base64
输出尺寸	自定义宽高，需满足四条约束，最大 3840×2160
画质档位	见画质与价格
输出格式	png（默认）、jpeg、webp
单次张数	1–10 张，默认 1
参考图	单张 ≤ 15 MB，整个请求 ≤ 50 MB，见上传限制
超时	建议将客户端超时设置为 600 秒，见耗时与超时

指定供应商

要点一般不需要指定；指定后该供应商不可用时，不会自动切换。

有内容审核方面的需求时可以指定，不同供应商的审核尺度不同，例如 gpt-image-2 在 Azure 上较严格、在 OpenAI 上相对宽松。

不指定（推荐）

请求→OfoxAI 网关→AzureOpenAI

网关在 Azure 与 OpenAI 之间自动选择可用的供应商。

指定供应商

请求openai→OfoxAI 网关→AzureOpenAI

请求只发往该供应商；该供应商不可用时，不会自动切换到其他供应商。

指定供应商的写法

请求头X-OfoxAI-Provider-Type: openai文生图和改图接口都适用；可选值为 azure_foundry、openai

请求体"extra_body": { "provider": { "type": "openai" } }仅文生图接口；改图接口是 multipart 上传，只能用请求头

完整说明见供应商路由。

常见报错

要点先看报错原文。安全拦截 moderation_blocked 和超时最常见。

报错	原因	怎么处理
`moderation_blocked`（Your request was rejected by the safety system）高频	提示词或参考图被上游安全系统拦截	修改提示词或参考图后再试，原样重试结果不变。有审核需求时可考虑指定供应商
请求超时、`504`、`524`、`Request timed out` 高频	客户端或中间代理（Nginx、Vercel、Cloudflare 等）的超时短于生成耗时	将客户端及中间代理的超时设置为 600 秒，见耗时与超时
`404 model_not_found`	模型 ID 拼错或大小写不对，如写成 `GPT-Image-2`	从本页复制模型 ID，全部小写
`provider_type_unavailable`	手动指定的供应商不提供这个模型	去掉供应商参数，让网关自动路由
`unknown provider type`	请求头里的供应商名拼错	检查拼写
`Invalid size`	尺寸不满足四条约束	见尺寸
`does not support quality 'xhigh'`	`gpt-image-2` 传了 `xhigh` 或 `max`	改用 `high`，或换 2.5
`Invalid value: 'standard'`	`quality` 传了 `standard` 或 `hd`	改用 `low` 到 `max`
`Invalid image file or mode`	参考图或 mask 格式不对	重新导出为标准 PNG 或 JPEG
`Invalid file 'image[0]': unsupported mimetype`	上传的文件不是图片	上传 PNG、JPEG 或 WebP 图片
`does not support the 'input_fidelity' parameter`	改图请求传了 `input_fidelity`	删除该参数。2.5 与 `gpt-image-2` 始终以高保真处理参考图
`Transparent background is not supported for JPEG output format`	透明背景配了 `jpeg` 格式	改用 `png` 或 `webp`
`Unknown parameter`	传了本系列不支持的参数	删掉该参数
`429 rate_limit_exceeded`	超过每分钟 100 次（按团队合计）	稍后重试。多加 Key 不会提高限额

完整错误码见 Error Handling。

报错原文

实测返回的完整报错，方便按原文搜索和比对：


Invalid size '1000x1000'. Width and height must both be divisible by 16.
Invalid size '4096x4096'. The longest edge must be less than or equal to 3840.
Invalid size '3200x1024'. The maximum supported aspect ratio is 3:1.
Invalid size '768x768'. Requested resolution is below the current minimum pixel budget.
The model 'gpt-image-2' does not support quality 'xhigh'.
Invalid value: 'standard'. Supported values are: 'low', 'medium', 'high', and 'auto'.
Invalid 'n': integer above maximum value. Expected a value <= 10, but got 11 instead.
Unknown parameter: 'style'.
The model 'gpt-image-2.5-sunburst' does not support the 'input_fidelity' parameter.
Transparent background is not supported for JPEG output format
Invalid file 'image[0]': unsupported mimetype ('text/plain; charset=utf-8'). Supported file formats are 'image/jpeg', 'image/png', and 'image/webp'.
unknown provider type in X-OfoxAI-Provider-Type header
Model 'GPT-Image-2' not found
Invalid image file or mode for image 1

注意 Invalid value: 'standard' 这条列出的可选值不完整：2.5 两款还支持 xhigh 和 max。以本页的档位表为准。

不生效的参数

要点不报错不等于生效。

以下参数传了不会报错，但对本系列没有效果，请求照常成功、照常计费：

参数	原因
`mask`（文生图接口）	只在改图接口生效
`response_format`	DALL·E 的旧参数，本系列固定返回 base64（`b64_json`）。直连 OpenAI 时会报 `Unknown parameter: 'response_format'`，通过 OfoxAI 调用会被忽略
`input_fidelity`（文生图接口）	属于 `gpt-image-1.5`。注意：传到改图接口会返回 400
`input_images`	属于 Qwen 图像系列

注意：不报错不等于生效。比如 style 会直接报错，而上面这几个会被悄悄忽略。

官方文档

OpenAI 官方文档写的是直连 OpenAI 时的行为。在 OfoxAI 上调用，以本系列文档的实测结论为准，例如价格以响应里的 usage 和模型页为准。

常见问题

GPT Image 2.5 的 size 支持任意尺寸吗？

可以自定义宽高，但必须同时满足四条约束：宽高都能被 16 整除、最长边不超过 3840、宽高比在 1:3 到 3:1 之间、总像素不低于 655,360。任何一条不满足都返回 400。例如 768x768 像素不够，会被拒绝，1024x768 可以。

不传 size 时输出多大？

由模型决定，不一定是 1024x1024，也不一定和参考图一致。实测文生图和改图都返回了 1254x1254。需要固定尺寸请显式传入。

gpt-image-2 支持 xhigh 和 max 画质吗？

不支持，传入会返回 400。xhigh 和 max 只有 gpt-image-2.5-flare 和 gpt-image-2.5-sunburst 支持。gpt-image-2 可选 low、medium、high、auto。

GPT Image 2.5 的 quality 可以填 hd 或 standard 吗？

不可以，会返回 400。可选值是 low、medium、high、xhigh、max、auto。不传时由模型自己选档，实测会选 low，想要稳定的画质请显式指定。

gpt-image-2 / GPT Image 2.5 API 超时设置多少合适？

建议将客户端超时设置为 600 秒。生成耗时随模型、画质和尺寸变化，高画质、大尺寸及改图请求可能需要数分钟。

GPT Image 报错 moderation_blocked（Your request was rejected by the safety system）怎么办？

提示词或参考图被上游安全系统拦截，常见于真实人物、受版权保护的角色或敏感内容。修改提示词或参考图后再试，原样重试结果不会改变。响应里的 error.moderation_details 会说明拦截发生在输入还是输出阶段。不同供应商的审核尺度不同，有审核需求时可考虑指定供应商。

GPT Image 报错 Unknown parameter: response_format 怎么办？

response_format 是 DALL·E 的旧参数，GPT Image 只返回 base64（data[0].b64_json），不提供图片 URL。删除 response_format，用 output_format 指定 png、jpeg 或 webp。通过 OfoxAI 调用时该参数会被忽略，不会报错。

调用 gpt-image 提示 Your organization must be verified 怎么办？

这是直连 OpenAI 时对组织的验证要求。通过 OfoxAI 调用不需要自行完成组织验证，使用 OfoxAI 的 API Key 即可调用 gpt-image-2.5-flare、gpt-image-2.5-sunburst 和 gpt-image-2。

GPT Image 请求超时、返回 504 或 524 怎么办？

接口为同步调用，高画质、大尺寸及改图请求可能需要数分钟。请将客户端超时设置为 600 秒，并检查 Nginx、Vercel、Cloudflare 等中间代理的超时设置，它们的默认值通常只有 60 至 100 秒。

GPT Image 报错 does not support the input_fidelity parameter 怎么办？

GPT Image 2.5 与 gpt-image-2 始终以高保真处理参考图，改图接口不接受 input_fidelity 参数，删除即可。该参数仅适用于 gpt-image-1.5。

GPT Image 报错 Invalid size 怎么办？

size 不满足四条约束之一。报错原文会说明是哪一条：divisible by 16 是宽高不是 16 的倍数；longest edge 是最长边超过 3840；aspect ratio 是宽高比超过 3:1；minimum pixel budget 是总像素不到 655,360，例如 768x768。改成满足四条的尺寸即可，比如 1024x768、1024x1024、1536x1024。

GPT Image 生成一张图多少钱？

按 token 计费，画质档位影响最大。OpenAI 官方参考价：gpt-image-2 生成 1024x1024 的图，low 约 $0.006，medium 约 $0.053，high 约 $0.211。2.5 两款输出图片每百万 token $30，1024x1024 的 low 约 $0.006。实际扣费以响应里的 usage 为准，OfoxAI 实时价格见模型页。

GPT Image 2.5 改图需要指定供应商吗？

不需要。Azure 和 OpenAI 两家都提供 2.5 的改图接口，网关会自动路由。