如何用 curl、Python 和 Node 调用 gpt-image-2.5 API（Flare 与 Sunburst）

OpenAI 于 2026 年 9 月 8 日发布 ChatGPT Images 2.5，并带上两个新的 API 模型：gpt-image-2.5-flare 和 gpt-image-2.5-sunburst。它们与 gpt-image-2 走同一批接口，所以如果你跟过我们的 gpt-image-2 API 指南，大部分代码换个模型 ID 就能活下来。变的是质量档位，以及 Responses API 如何按 tool call 选模型。

本指南只覆盖开发者路径：generations、带参考图和蒙版的 multipart edits、Responses API 工具、流式，以及读取 usage 来算真实费用。想看这次发布对 ChatGPT 用户意味着什么，读我们的 ChatGPT Images 2.5 概览；OpenAI 发布博文 给的是产品叙事。下面每个数字都来自 OpenAI 文档、定价页或计算器，读取于 2026 年 9 月 9 日。

AI Coding 交流群

如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。

gpt-image-2.5 API 速览

每 token 单价与 gpt-image-2；每张图费用仍会变，因为各质量档的 token 数变了。

前置条件

• 一个处于付费用量档的 OpenAI 开发者账号。图像接口需要 Tier 1 及以上，意味着要加支付方式；ChatGPT 订阅不算。我们的 OpenAI API key 指南覆盖了项目级 key。
• 官方 openai SDK，Python 或 Node。
• 一种预览图像响应的办法。curl 会打印 base64，迭代很痛苦；Apifox 能把解码后的图内联渲染，最后一节会把工作流迁过去。

先把 key 导出一次：

export OPENAI_API_KEY="sk-proj-..."

用 curl 生成一张图

先用 Flare；OpenAI 的 模型页 称它是“大多数应用的默认选择”。

curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Product photo of a matte black mechanical keyboard, studio lighting, no text",
    "size": "1536x1024",
    "quality": "medium",
    "output_format": "webp",
    "background": "transparent"
  }'

响应里有 data 数组，每张图一个 b64_json，外加 usage 对象，其中有 input_tokens 和 output_tokens。留着 usage；这是你能拿到的唯一准确费用信号。参数说明来自图像生成指南: output_format 默认为 png，OpenAI 说 “Using jpeg is faster than png”；output_compression（0-100）只对 jpeg 和 webp 生效；background: "transparent" 在 jpeg 上会失败。

Python：先生成，再用参考图编辑

SDK 调用与 curl body 镜像。解码 b64_json 并写成字节。

import base64
from openai import OpenAI

client = OpenAI()

gen = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Clean API analytics dashboard mockup, dark theme, latency chart top right",
    size="1536x1024",
    quality="high",
    output_format="png",
)
open("dashboard.png", "wb").write(base64.b64decode(gen.data[0].b64_json))
print(gen.usage.output_tokens, "output tokens")

编辑才是 2.5 模型真正值钱的地方；发布博文说它们“更擅长只改你要求的部分，同时保持其余细节不变”，OpenAI 把 Sunburst 定位为“编辑时控制更紧”。edits 接口是 multipart：一张参考图、可选蒙版，再加 prompt。蒙版透明处模型会重画，其余地方保留原图。

edit = client.images.edit(
    model="gpt-image-2.5-sunburst",
    image=open("dashboard.png", "rb"),
    mask=open("chart-area-mask.png", "rb"),
    prompt="Replace the latency chart with a bar chart of error rates per endpoint; keep everything else",
    size="1536x1024",
    quality="high",
)
open("dashboard-v2.png", "wb").write(base64.b64decode(edit.data[0].b64_json))
print(edit.usage.input_tokens, "input tokens (includes the reference image)")

去掉 mask 后，模型只根据 prompt 决定改什么。参考图按 image input tokens、$8/100 万计费；OpenAI 没有公布每张图的 input token 数，所以读 usage.input_tokens.

Node 和 TypeScript：把 b64_json 写到磁盘

import fs from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI();

const res = await client.images.generate({
  model: "gpt-image-2.5-flare",
  prompt: "Hero image for API docs: floating JSON cards over a teal gradient, no text",
  size: "1536x1024",
  quality: "medium",
  output_format: "jpeg",
  output_compression: 80,
});

const b64 = res.data?.[0]?.b64_json;
if (!b64) throw new Error("no image returned");
await fs.writeFile("hero.jpg", Buffer.from(b64, "base64"));

钉死 gpt-image-2.5-flare-2026-09-08 用在生产环境，避免 alias 漂移时输出跟着变。

Responses API：把图像生成当工具

这里由主模型读你的 prompt、改写，再调用 image_generation 工具。图像模型通过在工具定义里设置 model 来选；顶层 model 必须是主模型，OpenAI 的 工具文档 使用 gpt-6-astra。我们的 Responses API 指南覆盖请求形态。action 字段取 auto（默认）、generate 或 edit；设为 edit 当你传入参考图并希望它被修改而不是被重新诠释。

import base64

with open("product.png", "rb") as f:
    ref = base64.b64encode(f.read()).decode()

first = client.responses.create(
    model="gpt-6-astra",
    input=[{"role": "user", "content": [
        {"type": "input_text", "text": "Put this bottle on a white marble surface with soft daylight"},
        {"type": "input_image", "image_url": f"data:image/png;base64,{ref}"},
    ]}],
    tools=[{"type": "image_generation", "model": "gpt-image-2.5-sunburst", "action": "edit"}],
)
calls = [o for o in first.output if o.type == "image_generation_call"]
open("bottle-marble.png", "wb").write(base64.b64decode(calls[0].result))

second = client.responses.create(
    model="gpt-6-astra",
    previous_response_id=first.id,
    input="Same scene, but add a second bottle behind it, slightly out of focus",
    tools=[{"type": "image_generation", "model": "gpt-image-2.5-sunburst", "action": "edit"}],
)

这个 previous_response_id 跟进能把第一张图留在上下文里，于是“同一场景”不用重新上传文件。主模型 token 会叠在图像 token 之上，而且 prompt 会被改写，所以单靠 prompt 文本无法复现输出。

流式 partial 图像

两个 API 都接受 partial_images（0 到 3）。每张 partial 多收 100 个 output tokens，三张就是 300 tokens，约每图 $0.009。适合要展示进度的 UI；批处理任务里是浪费。

stream = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Isometric illustration of an API gateway routing requests to three services",
    size="1024x1024",
    quality="medium",
    stream=True,
    partial_images=2,
)
for event in stream:
    if event.type.endswith("partial_image"):
        open(f"gateway-partial-{event.partial_image_index}.png", "wb").write(
            base64.b64decode(event.b64_json))
    elif event.type.endswith("completed"):
        open("gateway.png", "wb").write(base64.b64decode(event.b64_json))

精确的事件类型字符串在图像生成指南里；用后缀判断能让循环同时兼容两种 API 变体。要在代码外检查流式事件，见我们测试 AI API SSE 响应的指南。

读取 usage，把 token 换成美元

OpenAI 自己的提醒：“Equal token rates don’t mean equal cost per image: token consumption can differ by model and quality setting.” 图像生成指南里的计算器给出了仅 image output tokens 的估算，费率 $30/100 万，来自定价页:

注意标签被重贴了。high 在 2.5 上用 1,756 tokens，相当于旧的 medium 预算，对应 gpt-image-2; max 用 7,024 tokens，相当于旧的 high 预算。保持 quality: "high" 贯穿迁移，每张图大约便宜 4 倍，用的是旧 medium 预算；要旧的 high 预算，改到 max。我们的 Flare vs Sunburst vs gpt-image-2 对比把月度账算全了。

计算器数字是估算。真实费用来自响应：

OUTPUT_RATE = 30 / 1_000_000  # dollars per image output token
usd = gen.usage.output_tokens * OUTPUT_RATE
print(f"{gen.usage.output_tokens} tokens = ${usd:.4f}")

按请求记日志；按 OpenAI 的说法，更大的非正方形尺寸有时比更小的正方形还少 token。一个未决问题：定价页 Batch 标签只列出 gpt-image-2，所以把 2.5 的 Batch API 支持当成未确认。

错误、速率限制和超时

• 429 速率限制。 带抖动退避，并尊重 Retry-After。2.5 模型页没有公布分档限额。作为参考，gpt-image-2 在 Tier 1 是每分钟 5 张和 100k TPM，到 Tier 5 是 250 IPM 和 8M TPM。
• insufficient_quota. 没有额度，或仍停在免费档。去加计费；不要重试。
• 审核拒绝。 prompt 或参考图触发了过滤器。改写，而不是重试；moderation: "low" 会放宽阈值。
• 超时。 OpenAI 文档写 “Complex prompts may take up to 2 minutes to process”。把客户端超时设得比这个高；Sunburst 天生比 Flare 更慢。

在 Apifox 里并排测 Flare 和 Sunburst

在终端里迭代图像 prompt 很慢，因为看不见输出，而且错误的 quality 每次发送都在花真钱。Apifox 是 API 客户端和测试平台：它负责发请求、检查响应；渲染发生在 OpenAI 的服务器上。

1. key 只存一次。 把 OPENAI_API_KEY 作为环境变量，并在 Authorization 头里引用为 Bearer {{OPENAI_API_KEY}}；key 不会进已保存的请求。
2. 两个环境，一个请求。 创建名为 flare 和 sunburst，各自带 MODEL 变量，并设置 "model": "{{MODEL}}" 的环境，body 里切换、重发，并排比较图像和 usage。编辑请用 form-data，把 image 和 mask 作为文件字段。
3. 解码 b64_json（后置操作）。 一小段脚本取出 data[0].b64_json，解码并存文件，于是每次发送都能在原始 JSON 旁边看到图。
4. 先对费用做断言，再排程。 断言 usage.output_tokens 不超过预算，例如 2,000 用于 high 的 1536x1024 渲染，再把请求做成定时回归。如果有人把质量改成 max，或快照把 token 数挪了，测试会在发票之前失败。

下载 Apifox，指向你的 OpenAI key，你就有一个带费用护栏的共享 prompt 库。

常见问题

用 2.5 需要改 gpt-image-2 代码吗？ 换模型 ID，并重新检查 quality。接口、鉴权和响应形态没变，但 high 现在对应更小的 token 预算。gpt-image-2 API 指南仍覆盖旧模型。

API 该选 Flare 还是 Sunburst？ 从 Flare 开始。OpenAI 把它定位为默认，延迟比 gpt-image-2 低 50%，token 单价相同。当编辑精度比速度更重要时再换 Sunburst，例如用参考照片做产品图。两者计算器 token 数相同，所以交易的是时间，不是美元。

这些模型能在 Chat Completions 里用吗？ 不能。图像生成在 Image API 和 Responses API 的 image_generation 工具上。Chat Completions 没有暴露它。

有没有免费途径用 API 试 2.5？ 没有永久免费的 API 档，图像接口需要 Tier 1。最便宜的实路是 quality: "low"，196 tokens，大约每张 1024x1024 $0.006。消费级应用是另一回事；见如何免费使用 ChatGPT Images 2.5。

接下来看什么

从 curl 调用开始，核对 usage.output_tokens 与计算器表，再把请求挪到能看见图的客户端。Simon Willison 的文章 展示了 Sunburst 在加入主体时仍保住图表；在你自己的参考图上测这种编辑行为，再做承诺。

开发必备：API 全流程管理神器 Apifox

介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。

如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。

值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。

获取专属报价与部署方案

详细的私有化部署系统架构与安全白皮书

针对您公司规模的专属报价单

免费的 1v1 专属产品演示 (Demo) 机会

获取部署方案

* 提交后，我们的客户经理将在 1 个工作日内与您联系

林俊锋 企业微信

@Apifox 专属顾问

扫码备注: 私有化 + 公司名