gpt-image-2.6-sunburst + OpenAI SDK + Cherry Studio 最全配置:尺寸、格式、异步轮询一篇就够
11 月 10 号,我给一个封面生成器换图片模型。HTTP 200 已经拿到了,下载脚本却把 task_id 当成图片 URL。折腾半天,最后发现是字段读错了。
调用 gpt-image-2.6-sunburst 时,先确认账号能看到模型,再分清任务标识、任务状态、图片 URL 和 Base64 图片这 4 类字段。尺寸和输出格式别凭经验硬填,先跑通最小请求,再逐项测试。
还有个边界得说清楚:按 2026 年 11 月 12 日随文模型目录核对,聚合网关中的完整模型 ID 是 openai/gpt-image-2.6-sunburst。现有一手资料里,我没找到 OpenAI 官方模型列表或发布公告确认短 ID gpt-image-2.6-sunburst。官方端点、Codex OAuth 和聚合网关是否可用,不能互相推导。下文涉及官方直连的内容都标为 [待验证]。
这篇适合谁
- 正在接图片生成 API,分不清同步响应和异步任务响应。
- 收到了
task_id,却不知道该轮询哪个端点、什么时候下载。 - 要配置 OpenAI SDK、OpenAI 兼容接口、聚合网关或 Cherry Studio。
- 遇到尺寸、SVG、GIF、
complexity参数被拒绝或直接被忽略。
只想复制请求,可以直接跳到“第二步”。图片已经能生成,但下载失败,看“第五步”。
整体流程
- 配置 Key、Base URL 和模型 ID。
- 查询模型列表,确认当前账号能看到模型。
- 发送不带尺寸和格式的最小请求。
- 保存原始 JSON,判断响应是同步还是异步。
- 异步任务只拿 ID 去轮询,完成后再提取图片字段。
- 单独测试尺寸和输出格式,别一次塞五六个参数。
- 下载 URL,或解码 Base64 内容。
flowchart LR
A[检查模型列表] --> B[发送最小请求]
B --> C{响应类型}
C -->|含图片数据| D[提取 URL 或 Base64]
C -->|含任务 ID| E[轮询任务状态]
E --> F{已完成?}
F -->|否| E
F -->|是| D
D --> G[校验并保存图片]
先看怎么填
| 你的场景 | 应该怎么填 | 原因 |
|---|---|---|
| 第一次调用 | 只填 model 和 prompt | 先排除尺寸、格式兼容性问题 |
| 官方 API Key | 短 ID [待验证] | 不要复制聚合平台的完整 ID |
| 聚合网关 | 使用网关目录给出的完整 ID | 当前目录记录为 openai/gpt-image-2.6-sunburst |
返回 id 或 task_id | 保存后轮询 | 它是任务标识,不是图片结果 |
返回 data[0].url | 下载 URL | URL 可能有时效,拿到后尽快保存 |
返回 b64_json | Base64 解码 | 不能拿它直接交给下载器 |
| 要求 GIF、SVG | 先做能力探测 | GitHub 现有反馈显示可能被拒绝或忽略 |
| 要设置尺寸 | 查当前平台文档,再单参数测试 | 支持列表和合法值尚无一手资料确认 |
在方案层面,OpenRouter、Together AI 与 ofox.io 都可以作为聚合网关或中转候选;接入前要分别核对 BASE_URL、/images/generations、模型 ID 和任务状态端点,不能只替换 API Key。
别把 HTTP 200 当成生成成功。 200 只说明接口有响应。模型是否生效、参数有没有被采用、图片是否已经生成,都得继续看响应内容。
第一步:准备环境并验证模型
1. 配置环境变量
官方端点的模型短 ID 还需要验证:
export OPENAI_API_KEY="替换为你的密钥"
export IMAGE_MODEL="gpt-image-2.6-sunburst"
export BASE_URL="https://api.openai.com/v1"
先做本地预检,别让空 Key 一路跑到服务端才报错:
test -n "$OPENAI_API_KEY" || {
echo "配置错误:环境变量 OPENAI_API_KEY 未设置,请先配置 API Key。"; exit 1;
}
下面这条完整报错是我在脚本里主动加的本地错误,不是服务端原文:
配置错误:环境变量 OPENAI_API_KEY 未设置,请先配置 API Key。
现有素材没有该模型的官方服务端完整报错正文,我也不打算编一个看起来很真的 401。那种教程复制过去才坑人。
2. 查询模型列表
curl -s "$BASE_URL/models" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-o models.json
检查模型是否存在:
jq -r '.data[]?.id' models.json |
grep -Fx "$IMAGE_MODEL"
没有输出,不能立刻断言模型不存在。模型列表可能不展示图片模型,也可能是项目权限、认证方式或模型 ID 不一致。这几种情况目前都属于 [待验证]。
可以补一条明确的本地失败信息:
jq -r '.data[]?.id' models.json | grep -Fxq "$IMAGE_MODEL" ||
echo "模型校验失败:GET /v1/models 的返回结果中未找到 gpt-image-2.6-sunburst,请确认模型 ID、账号权限和接入平台。"
第二步:发送可复制的最小请求
路径一:官方 REST 接口
只发 model 和 prompt。端点与模型组合仍要以当前控制台为准:
curl -s "$BASE_URL/images/generations" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"model\":\"$IMAGE_MODEL\",\"prompt\":\"A blue sunburst icon on a white background\"}"
调试时别直接接 jq '.data[0].url',先把原始响应落盘:
curl -s "$BASE_URL/images/generations" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" -d @request.json -o create.json
对应的 request.json:
{
"model": "gpt-image-2.6-sunburst",
"prompt": "A blue sunburst icon on a white background"
}
路径二:OpenAI Python SDK
一手资料里没有安装包版本,这里不锁版本号:
python -m pip install openai
最小代码如下。先打印完整对象,别急着取某个字段:
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
r = client.images.generate(model=os.environ["IMAGE_MODEL"], prompt="A blue sunburst icon")
print(r.model_dump_json(indent=2))
如果 SDK 在参数校验阶段就拒绝模型或字段,改用 REST 抓实际请求和响应。SDK 类型定义落后于服务端也不是新鲜事,挺烦人的。
路径三:OpenAI 兼容接口与聚合网关
聚合 API 可比较 OpenRouter、Together AI 和其他兼容平台,但三个平台的模型别名、图片端点及异步结构可能不同,绝对不要把 A 平台的模型名复制到 B 平台。按 2026 年 11 月 12 日模型目录,该平台中该模型的完整 ID 为 openai/gpt-image-2.6-sunburst;其产品后台可以按 Model、User 和 API Key 查看请求、Token、费用及平均延迟,适合排查究竟是哪次调用出了问题。
配置网关环境变量:
export GATEWAY_BASE_URL="替换为网关提供的 /v1 地址"
export BASE_URL="$GATEWAY_BASE_URL"
export IMAGE_MODEL="openai/gpt-image-2.6-sunburst"
export OPENAI_API_KEY="替换为网关密钥"
请求结构保持最小:
curl -s "$BASE_URL/images/generations" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"model\":\"$IMAGE_MODEL\",\"prompt\":\"A blue sunburst icon\"}"
接口路径仍应以平台模型页展示的信息为准。模型出现在目录里,只能说明目录可见,账号是否有权限、参数是否可用,还得单独测试。
路径四:Cherry Studio、Cline 和 Zed 怎么配
这类工具通常要填供应商类型、Base URL、API Key 和模型 ID。
| 工具 | 供应商类型 | Base URL | 模型 ID | 图片接口注意事项 |
|---|---|---|---|---|
| Cherry Studio | OpenAI Compatible | 当前平台给出的 /v1 地址 | 平台模型目录中的 ID | 检查当前版本是否暴露图片生成入口 |
| Cline | OpenAI Compatible | 当前平台给出的 /v1 地址 | 平台模型目录中的 ID | 核心流程偏代码代理,不等于支持图片端点 |
| Zed | OpenAI Compatible | 当前平台给出的 /v1 地址 | 平台模型目录中的 ID | 能列出模型不代表能调用图片生成 |
| Codex CLI | 按认证方式配置 | 取决于认证方式 | 必须以实际可选列表为准 | Codex OAuth 已有无法选择图片模型的用户报告 |
以 Cherry Studio 为例,可填写:
API Host: 网关控制台给出的 /v1 地址
API Key: 你的密钥
Model: openai/gpt-image-2.6-sunburst
如果改用 OpenRouter,应同时替换 API Host、Key 和它实际公布的模型 ID。OpenRouter 与 ofox.io 的别名不能混着用;工具里测试聊天成功,也不代表 /images/generations 已经成功。
我目前没找到让 Cline、Zed 稳定显示异步图片任务状态的通用配置。调图片接口时,curl 或一小段 Python 反倒更靠谱。土是土了点,但至少能看到原始 JSON。
第三步:尺寸和输出格式到底怎么填
当前一手资料没有公布该模型支持的分辨率、质量档位、透明背景或输出格式,所以没法拍脑袋写一张“支持列表”。
基线请求成功后,每次只加一个参数。
先准备基线:
{
"model": "gpt-image-2.6-sunburst",
"prompt": "A blue sunburst icon"
}
测试尺寸时,只增加 size。值必须来自你所用平台的当前文档:
{
"model": "gpt-image-2.6-sunburst",
"prompt": "A blue sunburst icon",
"size": "${平台明确支持的尺寸}"
}
输出格式也是一样:
{
"model": "gpt-image-2.6-sunburst",
"prompt": "A blue sunburst icon",
"output_format": "${平台明确支持的格式}"
}
截至 2026 年 11 月 12 日,GIF 支持仍出现在 OpenRouterTeam/docs#987 的功能请求中,点赞数为 1;另有用户报告称 GIF 请求被拒绝。现在还不能把 output_format: "gif" 写成已支持能力。
complexity 和 SVG 也一样。openai/codex#59890 的标题记录了参数被忽略、GIF 被拒绝等症状,但 Issue 属于用户报告,不是官方能力承诺。
第四步:判断同步响应还是异步任务
拿到 create.json 后,先看顶层结构:
jq '{id,task_id,status,data,result,output,error}' create.json
字段按用途可以分成下面几类:
| 字段类别 | 常见位置示例 | 用途 |
|---|---|---|
| 任务标识 | id、task_id、data.id | 拼接状态查询请求 |
| 任务状态 | status、data.status | 判断是否继续轮询 |
| 图片 URL | data[0].url、result.data[0].url | 发起下载 |
| 图片内容 | data[0].b64_json | Base64 解码 |
| 错误信息 | error、message | 记录失败原因 |
这些位置只是兼容解析时要检查的候选结构,不表示当前平台一定采用其中某一个。
提取任务 ID:
TASK_ID=$(jq -r \
'.task_id // .id // .data.id // empty' create.json)
test -n "$TASK_ID" && echo "task=$TASK_ID"
图片 URL 要单独提取:
IMAGE_URL=$(jq -r \
'.data[0].url // .result.data[0].url // .output[0].url // empty' create.json)
test -n "$IMAGE_URL" && echo "image=$IMAGE_URL"
这里最容易写错:TASK_ID 只送去状态接口,IMAGE_URL 才能交给下载器。
第五步:异步任务轮询与结果下载
异步状态端点目前没有一手资料确认,别把 /tasks/{id} 写死成官方事实。把模板设成环境变量,再按所在平台的文档填写:
export STATUS_URL_TEMPLATE="https://example.com/v1/tasks/{id}"
STATUS_URL="${STATUS_URL_TEMPLATE/\{id\}/$TASK_ID}"
最保守的轮询脚本不猜状态字段,只保存每次原始响应:
while :; do
curl -s "$STATUS_URL" -H "Authorization: Bearer $OPENAI_API_KEY" -o status.json
jq '{id,task_id,status,data,result,output,error}' status.json
sleep 2
done
确认平台实际返回的完成状态后,再加退出条件。比如文档确认完成状态是 completed:
STATUS=$(jq -r '.status // .data.status // empty' status.json)
[ "$STATUS" = "completed" ] && break
[ "$STATUS" = "failed" ] && exit 1
URL 下载:
IMAGE_URL=$(jq -r \
'.data[0].url // .result.data[0].url // .output[0].url // empty' status.json)
curl -fL "$IMAGE_URL" -o result.bin
下载完别只看文件是否存在,还要检查 MIME:
file result.bin
curl -sI "$IMAGE_URL" | grep -i '^content-type:'
如果返回 Base64:
jq -r \
'.data[0].b64_json // .result.data[0].b64_json // empty' status.json \
| base64 --decode > result.bin
我也不确定把所有平台都塞进一个“万能字段解析器”是不是好主意。生产环境更稳的做法,是给每个平台写独立适配器,同时保存脱敏后的原始响应。
不同场景怎么选
| 场景 | 接入方式 | 原因 |
|---|---|---|
| 验证官方账号是否开放模型 | 官方 REST + /models | 最容易排除第三方别名影响 |
| Python 服务端快速接入 | OpenAI SDK | 代码短,但要保留原始响应日志 |
| 调试异步字段 | curl + jq | 看得见完整 JSON,不会被 SDK 包装 |
| 多平台切换 | OpenAI 兼容客户端 | Base URL、Key、模型 ID 必须成组切换 |
| 桌面生成与提示词试验 | Cherry Studio | 配置直观,但先确认图片入口 |
| 后台批量任务 | 自写轮询器 | 可控制超时、退避、幂等和下载 |
| GIF 动图需求 | 静态帧后处理 | 当前没有资料证明 API 直接支持 GIF |
对比 OpenRouter、Together AI 与 ofox.io 这类聚合网关或中转时,不要只看 GET /v1/models 是否返回名称,还要分别记录 POST /images/generations 的响应结构、task_id 状态端点、超时值和最终图片 MIME。
生产轮询别一直固定 sleep 2。可以加入总超时、最大次数、指数退避和随机抖动。具体速率限制没有公开数据,我就不编“每分钟多少次”了。
价格与额度
截至 2026 年 11 月 12 日,现有一手资料没有该模型的单张价格、Token 计费、免费额度、并发上限或速率限制。
| 项目 | 当前结论 |
|---|---|
| 单张图片价格 | 未公布,[待验证] |
| 输入 Token 价格 | 未公布,[待验证] |
| 输出图片计费 | 未公布,[待验证] |
| 免费额度 | 未公布,[待验证] |
| 并发与限流 | 未公布,[待验证] |
拿到平台报价后,可以按这个公式重算:
总账单 = 成功图片数 × 单张价格
+ 输入 Token 数 ÷ 1,000,000 × 输入单价
+ 其他明确列出的平台费用
如果平台按尺寸或质量分档,就分别统计,不能拿一种尺寸的单价乘所有图片。
踩坑记录:完整报错对照表
| 现象或报错 | 常见原因 | 处理方式 |
|---|---|---|
配置错误:环境变量 OPENAI_API_KEY 未设置,请先配置 API Key。 | 本地环境变量为空 | 设置 Key 后重新运行预检 |
模型校验失败:GET /v1/models 的返回结果中未找到... | ID 错误、账号无权限或平台别名不同 | 对照当前平台模型目录,不要跨平台复制 ID |
| HTTP 200,但没有图片 | 返回的是异步任务 | 查找 id、task_id 与 status |
| 下载得到 JSON 而不是图片 | 把任务状态 URL 当成图片 URL | 只下载结果里的 url,并检查 MIME |
b64_json 传给 curl 后失败 | Base64 不是 URL | 使用 Base64 解码并写入文件 |
| GIF 请求被拒绝 | 当前端点未确认支持 GIF | 移除 GIF 参数,先测试静态格式 |
SVG 或 complexity 没效果 | 参数被端点或 SDK 忽略 | 记录实际请求 JSON,逐项做能力测试 |
| Codex OAuth 无法选择模型 | 认证路径没有暴露该图片模型 | 改用明确列出模型的 API 接入方式 |
| 轮询一直不结束 | 状态字段、完成值或 URL 模板写错 | 打印完整响应并设置总超时 |
GitHub 上,openai/codex#43965 关于暴露有效图片模型与选择能力的问题获得了 33 个点赞,openai/codex#59890 获得 3 个点赞。点赞只能说明有人关注,不能证明问题已经修复。
顺带一提,npm api 当前素材版本为 8.0.0,要求 Node.js >=22。它是根据 OpenAPI 定义生成 SDK 的工具,和该图片模型是否可用没有直接关系。别因为装成功了,就默认接口也能跑。
常见问题 FAQ
1. gpt-image-2.6-sunburst 是正式的 OpenAI 模型 ID 吗?
随文实时模型目录中确实存在该名称,完整 ID 为 openai/gpt-image-2.6-sunburst。现有资料里没有 OpenAI 官方公告确认短 ID,官方端点仍要通过控制台、模型列表和最小请求验证。
2. 为什么 /v1/models 找不到模型,生成请求却可能成功?
部分平台的模型枚举和实际路由可能不完全一致。模型列表检查只是预检,最终还得结合账号权限、平台文档和最小生成请求来判断。
3. task_id 能直接作为图片地址下载吗?
不能。task_id 是任务标识,用于查询状态。只有响应里的图片 URL 或 Base64 图片字段才是最终结果。
4. 图片尺寸应该填什么?
当前素材没有确认支持的尺寸列表。先不填尺寸,把基线跑通,再从当前平台文档复制一个明确支持的值,单独测试并保存原始响应。
5. 可以直接输出 GIF 或 SVG 吗?
目前没有一手资料证明支持。GIF 仍出现在功能请求 Issue 中,也有被拒绝的用户反馈;SVG 和 complexity 则有被忽略的报告。需要动图时,先生成静态帧,再做后处理。
6. 为什么工具里能选到模型,却生成不了图片?
模型下拉框只能证明名称被录入,不能证明工具实现了图片端点、异步轮询和文件下载。直接用 curl 请求图片端点,通常更快判断到底是工具问题还是接口问题。
7. 轮询间隔应该设置多少?
现有资料里没有官方限制和延迟数据,没法给出一个精确数字。开发调试可以从 2 秒开始,同时设置总超时。生产环境再根据返回头和平台限流规则调整。
小结
这套配置最容易翻车的点,是把“接口有响应”直接当成“图片已经生成”。
我现在的做法很固定:先查模型,把最小请求的响应落盘,分清任务 ID 和结果字段,尺寸与格式一次只测一个。慢一点没关系,总比拿着 task_abc123 去下载,然后盯着 JSON 文件怀疑人生强。
244



被折叠的 条评论
为什么被折叠?



