GPT-Image-2.6 API 通过 OpenAI 的两款模型 gpt-image-2.6-flare 与 gpt-image-2.6-sunburst 生成并编辑图像。调用时只需携带 API Key 向 POST /v1/images/generations 发送提示词,再对响应中的 b64_json 进行解码即可。2.6 版本新增了图像标注引导编辑(image markup)、SVG 与 GIF 输出,以及 complexity 参数。
本文涵盖鉴权配置、首次生图请求、标注引导编辑、SVG 导出,以及 quality 与 complexity 参数设置。本文重点介绍 2.6 的新增特性(流式输出与 Responses API 工具调用方式与 2.5 版本保持一致)。下文所有请求示例均根据 2026 年 11 月 5 日的 OpenAI 官方文档编写,尚未用线上 API Key 实测,上线前请务必先行测试。
AI Coding 交流群
如果你也在用 AI 写代码,或者正在研究 Cursor、Claude Code 这些工具,欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流,还有各种新工具和新玩法。
GPT-Image-2.6 API 核心信息速览
| 项目 | 详情 |
|---|---|
| 模型 ID | gpt-image-2.6-flare、gpt-image-2.6-sunburst |
| 生成端点 | POST /v1/images/generations |
| 编辑端点 | POST /v1/images/edits |
| 鉴权方式 | Authorization: Bearer $OPENAI_API_KEY |
| 输出格式 | b64_json;默认 PNG,另支持 JPEG、WebP、GIF、SVG |
quality |
low、medium、high、xhigh、max、auto(默认) |
complexity |
low、medium、high(省略时默认为 high) |
| 图像 token 价格 | 输入 $8 / 1M、缓存输入 $2 / 1M、输出 $30 / 1M |
| 文本 token 价格 | 输入 $5 / 1M、缓存输入 $1.25 / 1M |
以上费率整理自 OpenAI 定价页面。两款模型的单 token 价格完全一致,选型主要取决于速度需求与编辑精度。
Flare 还是 Sunburst:该调用哪款模型?
快速迭代和日常生图建议调用 Flare。OpenAI 表示它在 low 画质下最快约 6 秒即可返回图像,并改进了海报与商品图的排版表现。精细创作与多轮连续编辑则建议调用 Sunburst,OpenAI 称其在 medium 或 high 画质下具备更好的跨轮次一致性。
以上均为 OpenAI 官方说明,并非独立基准测试结果,两款模型自 2.5 版本起即延续了速度优先与精度优先的双线定位。
鉴权与环境准备
发起第一次调用前需要准备三件事:
- 在 OpenAI 控制台创建 API Key,并将其导出为环境变量
OPENAI_API_KEY。 - 如果你的组织被要求验证,请先完成 API 组织验证(API Organization Verification)。OpenAI 表示部分组织必须完成该验证后才能调用 GPT Image 模型。
- 运行
curl示例需安装jq,运行 Python 示例需安装openai包。
如果你的应用面向终端个人用户,建议同时传入最长 128 个字符的哈希值 safety_identifier,该字段已取代弃用的 user 参数。
生成第一张图片
下面这条请求使用 low 画质调用 Flare,适合快速生成草稿:
curl --fail-with-body --silent --show-error \
https://api.openai.com/v1/images/generations \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-flare",
"prompt": "A minimal poster for a developer meetup, with the words SHIP IT in bold type",
"size": "1024x1536",
"quality": "low",
"complexity": "low"
}' | jq -er '.data[0].b64_json' | base64 --decode > poster.png
使用 Python 发起同类调用:
import base64
from pathlib import Path
from openai import OpenAI
client = OpenAI()
result = client.images.generate(
model="gpt-image-2.6-sunburst",
prompt="A product shot of a ceramic mug on a walnut desk, soft morning light",
size="1536x1024",
quality="medium",
extra_body={"complexity": "low"},
)
Path("mug.png").write_bytes(base64.b64decode(result.data[0].b64_json))
这里通过 extra_body 传入 complexity,这样即使当前安装的 SDK 版本尚未将其暴露为具名参数,调用也能正常工作。GPT Image 模型始终返回 base64 数据,因此不要传 response_format,也不要在响应中查找 url 字段。
OpenAI 指南建议读取响应中的 usage 对象来统计 token 消耗。虽然 API 参考文档将该字段描述为仅适用于 gpt-image-1,但其示例响应中包含了该对象;在基于它搭建成本统计前,请先确认你的 2.6 响应中确实返回了该字段。
使用标注(Markup)编辑图片
标注(Markup)用于告诉模型需要在画面的哪个位置做修改。调用时需同时传入原图、带有圈选或涂鸦标记的透明背景 PNG 叠加层,以及描述修改内容的提示词:
curl --fail-with-body --silent --show-error \
https://api.openai.com/v1/images/edits \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-flare",
"images": [{"image_url": "https://your-bucket.example/kitchen.png"}],
"markup": {"image_url": "https://your-bucket.example/vase-overlay.png"},
"prompt": "Recolor the vase inside the red circle to solid cobalt blue. Keep everything else unchanged. Remove the red circle.",
"quality": "medium",
"complexity": "low"
}' | jq -er '.data[0].b64_json' | base64 --decode > vase.png
JSON 请求使用 images 数组和 markup 对象(其中 markup 必须且只能包含 image_url 或 file_id 之一)。image_url 可以是 HTTPS URL 或 base64 Data URL。如果使用 multipart 表单请求,则改为直接上传文件,图像生成指南中提供了对应的 Python 示例。

标注叠加层有严格的格式要求:
- 旋转方向对齐后,叠加层的宽高必须与第一张输入图片完全一致。
- 必须包含透明像素,不能把标记直接合并(flatten)到原图上。
- 叠加层仅作用于第一张输入图片,其余输入图片仅作为参考图。
- 原图与叠加层各自最多不超过 16,777,216 像素,叠加层文件大小不得超过 50 MB。
markup不能与mask或prompt_rewriter同时使用。
请像 OpenAI 官方示例一样,在提示词中明确要求模型移除标注线。标注编辑的计费方式与普通编辑相同。Responses API 暂不支持 markup,在该接口中请继续使用 mask。
导出 SVG
对于需要可编辑路径的图标、Logo 和插画,可以在生成端点上将 output_format 设为 svg:
curl --fail-with-body --silent --show-error \
https://api.openai.com/v1/images/generations \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-sunburst",
"prompt": "A flat two-color wheat logo for a bakery called Field and Flour",
"output_format": "svg",
"quality": "medium",
"n": 1
}' | jq -er '.data[0].b64_json' | base64 --decode > logo.svg
API 会先渲染一张受 quality 控制的参考图,再根据参考图生成 SVG 代码。解码后的字节流是 UTF-8 编码的 XML,不含脚本、外部资源或内嵌位图。
SVG 输出有以下四项限制:
n必须为 1。- 不支持流式输出(streaming)、渐进式局部图像(partial images)、
output_compression和prompt_rewriter。 - 编辑端点(edits)不能输出 SVG,也不接受 SVG 作为位图输入。
- 可选的
svg对象可用于指定矢量生成模型,但仅限已开通 SVG 模型选择权限的账号;未开通时请勿传该字段。
SVG 请求会按两部分计费:参考图按图像费率计费,矢量代码生成按对应模型的 token 费率计费。API 参考文档为第二部分单独列出了 svg_usage 对象,建议在日志中一并记录。
生成 GIF
API 直接返回合成好的 GIF 文件,而非精灵图。只需在生成请求中加上三个字段:
{
"model": "gpt-image-2.6-flare",
"prompt": "A small orange robot waves, blinks and returns to its starting pose. Make it loop.",
"output_format": "gif",
"frame_count": 9,
"frame_duration_ms": 200,
"size": "auto"
}
以同样的方式解码 b64_json 并保存为 .gif 文件即可。调用前请先确认两点:
- 帧数上限。 官方指南称
frame_count取值范围为 2 到 64,但 API 参考文档写的是 2 到 16。在实测确认更高帧数可用前,建议保持在 16 帧以内。 - 访问权限。 API 参考文档指出 GIF 输出需要开通所选模型的 GIF 预览权限(GIF preview access),而指南中并未提及。如果 GIF 请求被拒绝,可能是权限尚未开通,而非请求体格式有误。
GIF 输出不支持流式传输、渐进式局部图像或自定义 output_compression,编辑端点也不支持返回 GIF。OpenAI 尚未公布专门的 GIF 计费公式,放量调用前建议先做小规模测试并核对账单。
设置 quality 与 complexity
quality 控制渲染细节并直接决定输出 token 成本;complexity 控制模型在渲染前的规划深度,调整它不会产生单独的附加费率。
建议在每次请求中显式设置 complexity。它的默认值为 high,但 OpenAI 建议大多数编辑任务使用 low。官方指南提醒,过高的复杂度设置可能增加响应延迟,并引入不必要的画面变动。

quality 决定了输出部分的费用。下表基于 11 月 5 日 OpenAI 价格计算器对 1024x1024 图片的估算(不含输入 token):
quality |
输出 token 数 | 输出成本 |
|---|---|---|
low |
823 | $0.02469 |
medium |
1,449 | $0.04347 |
high |
1,756 | $0.05268 |
xhigh |
3,122 | $0.09366 |
max |
7,024 | $0.21072 |
medium 与 high 之间的差价约为 1 美分,建议对比测试后再作取舍。定价页面的 Batch 标签页目前尚未纳入 2.6,请勿默认 2.5 的批处理半价优惠同样适用。
处理错误与超时
建议按“重试是否有效”来分类处理错误:
| 错误类型 | 处理方式 |
|---|---|
| 速率限制(Rate limit)或服务端错误 | 采用退避策略重试 |
| 配额不足(Quota error) | 不要重试;先充值或检查账单设置 |
error.type 为 image_generation_user_error |
先修改提示词或输入图片 |
error.code 为 moderation_blocked |
查看 moderation_details 后修改内容 |
在代码中应以 error.code 作为稳定的判断条件,并记录请求 ID。moderation_details 中包含 moderation_stage 和粗粒度的 categories,这些信息适合写进服务端日志,不宜直接展示给终端用户。由于 OpenAI 表示复杂提示词最长可能耗时两分钟,请将客户端超时时间设在两分钟以上。
使用 Apifox CLI 让编程智能体测试接口
以下以 Apifox CLI 演示如何让编程智能体把上述请求与参数限制整理成自动化测试。先完成一次性安装与配置:
npm install -g apifox-cli@latest
apifox auth login --with-token <YOUR_TOKEN>
apifox skill install
随后向 Claude Code、Codex 或 Cursor 提供一条提示词:
In Apifox project <id>, add POST /v1/images/generations and POST /v1/images/edits
on https://api.openai.com. Read the bearer token from OPENAI_API_KEY.
Create test cases for gpt-image-2.6-flare at low quality and low complexity:
1. PNG generation: assert status 200 and data[0].b64_json exists.
2. SVG generation: assert status 200 and output_format equals svg.
3. GIF with frame_count 6: assert status 200 and output_format equals gif.
4. SVG with n set to 2: assert a 4xx status and that error.message exists.
5. GIF with frame_count 17: record the status, because OpenAI's docs disagree.
Put them in a test suite named "GPT-Image-2.6", run it against environment
<envId>, and summarize every failure.
示例中,智能体读取 schema、校验载荷后创建并运行测试套件:
apifox cli-schema get endpoint-create
apifox cli-schema validate endpoint-create --file endpoint.json
apifox endpoint create --project <id> --file endpoint.json
apifox cli-schema get test-case-create
apifox cli-schema validate test-case-create --file case.json
apifox test-case create --project <id> --file case.json
apifox cli-schema validate test-suite-create --file suite.json
apifox test-suite create --project <id> --file suite.json
apifox test-suite run <suiteId> --project <id> -e <envId> \
--env-var "OPENAI_API_KEY=$OPENAI_API_KEY" --on-error continue -r cli,json
用例 5 可以帮你实测当前账号的 GIF 帧数上限,用例 3 则能确认账号是否已具备 GIF 权限。执行通过的用例会产生真实的计费生成,因此测试时请保持 low 画质。如需接入持续集成,可将报告格式换为 -r junit 并参考 CI/CD 流水线指南,同时在 Claude Code 等编程智能体中启用对应的自动化测试技能。
常见问题
GPT-Image-2.6 API 的模型名称是什么? gpt-image-2.6-flare 和 gpt-image-2.6-sunburst。与 2.5 模型不同,API 参考文档目前尚未列出带日期的快照版本。
GPT-Image-2.6 API 如何收费? 图像 token 价格为输入 $8 / 1M、输出 $30 / 1M。不含输入 token 时,生成一张 1024x1024 图片在 low 画质下输出成本约为 $0.025,在 high 画质下约为 $0.053。
应该从 gpt-image-2.5 迁移到 2.6 吗? 如果需要 SVG、GIF 或 complexity 控制,建议迁移。但迁移前请先核算成本:low 画质单张图片消耗的 token 约为 2.5 的 4.2 倍,且 2.6 模型目前尚未公布 Batch 批处理折扣价。
可以在编辑端点(edits)上使用 complexity 吗? 可以。OpenAI 建议大多数编辑请求使用 low。
可以通过 API 把上传的图片转成 GIF 吗? 不可以。编辑端点不支持返回 GIF 或 SVG,这两种格式都只能在生成端点(generations)上从文本提示词开始生成。
API 会返回图片 URL 吗? 不会。GPT Image 模型始终在 b64_json 中返回 base64 字符串,需要自行解码并持久化存储文件。