如何使用 GPT-Image-2.6 API

详解 GPT-Image-2.6 API 的鉴权准备、Flare 与 Sunburst 生图调用、标注引导编辑、SVG 与 GIF 导出,以及 quality 和 complexity 参数设置。

用 Apifox,节省研发团队的每一分钟

如何使用 GPT-Image-2.6 API

免费使用 Apifox

相关推荐

最新文章

API

一体化协作平台

API 设计

API 文档

API 调试

自动化测试

API Mock

API Hub

立即体验 Apifox
目录

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 编程的实际用法、开发工作流,还有各种新工具和新玩法。

AI Coding 交流群二维码

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 版本起即延续了速度优先与精度优先的双线定位。

鉴权与环境准备

发起第一次调用前需要准备三件事:

  1. 在 OpenAI 控制台创建 API Key,并将其导出为环境变量 OPENAI_API_KEY。
  2. 如果你的组织被要求验证,请先完成 API 组织验证(API Organization Verification)。OpenAI 表示部分组织必须完成该验证后才能调用 GPT Image 模型。
  3. 运行 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 示例。

GPT-Image-2.6 标注编辑流程图:将原始照片、透明 PNG 标注叠加层和文本提示词发送至 POST /v1/images/edits,返回完成修改并移除红圈标注的图像

标注叠加层有严格的格式要求:

  • 旋转方向对齐后,叠加层的宽高必须与第一张输入图片完全一致。
  • 必须包含透明像素,不能把标记直接合并(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。官方指南提醒,过高的复杂度设置可能增加响应延迟,并引入不必要的画面变动。

GPT-Image-2.6 推荐起始参数网格:快速草稿使用 Flare + low quality + low complexity,聚焦编辑使用 low complexity,最终精细大图使用 Sunburst + medium/high quality,密集排版使用 medium/high complexity

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 字符串,需要自行解码并持久化存储文件。