GPT Image
用 GPT Image 生成和编辑图片:参数、返回与注意事项。
| 项目 | 值 |
|---|---|
| Base URL | https://api.hop-base.com/v1 |
| 生成图片 | POST /v1/images/generations |
| 编辑图片 | POST /v1/images/edits |
| 查询异步任务 | GET /v1/images/tasks?task_id=… |
| 密钥分组 | 「GPT Image 全系」;gpt-image-2.5-flare 与 gpt-image-2.5-sunburst 也可用「GPT 官方直连(Azure)」 |
默认同步返回 Base64 图片,加 Prefer: respond-async 可改为异步任务;Codex Plus、Codex Pro 等只含对话模型的分组的密钥调 gpt-image-* 会返回 404。「GPT 官方直连(Azure)」分组的生图同步返回 Base64。
可用型号
| 型号 | 模型 ID | quality 档位 | 官方价 |
|---|---|---|---|
| GPT Image 2.6 Flare | gpt-image-2.6-flare | low / medium / high / xhigh / max | $5 / $30/ 百万 tokens |
| GPT Image 2.6 Sunburst | gpt-image-2.6-sunburst | low / medium / high / xhigh / max | $5 / $30/ 百万 tokens |
| GPT Image 2.5 Flare | gpt-image-2.5-flare | low / medium / high / xhigh / max | $5 / $30/ 百万 tokens |
| GPT Image 2.5 Sunburst | gpt-image-2.5-sunburst | low / medium / high / xhigh / max | $5 / $30/ 百万 tokens |
| GPT Image 2 | gpt-image-2 | low / medium / high | $5 / $30/ 百万 tokens |
选型建议:日常出图首选 Flare;要画质选 Sunburst,同参数下比 Flare 略慢;gpt-image-2 是通用型号,ID 是 gpt-image-2,不是 gpt-image-2.0。参考耗时(单张 1024x1024):low 档 2.5 两个型号约 14 秒,high 档 Flare 约 19 秒、Sunburst 约 37 秒。
GPT Image 2.6(2026-11-04 发布)与 2.5 同价,新增 complexity 参数与 SVG、GIF 动图输出;Flare 是速度档,Sunburst 是画质档。参考耗时(单张 1024x1024):Flare low 约 14 秒、high 约 20 秒、xhigh 约 29 秒、max 约 46 秒;Sunburst low 约 29 秒、high 约 66 秒、xhigh 约 90 秒。
请求参数
生成
POST /v1/images/generations,JSON 请求体。
| 参数 | 必填 | 类型与限制 | 默认 | 说明 |
|---|---|---|---|---|
model | 必填 | string | — | 上表的 ID 之一 |
prompt | 必填 | string,≤ 32,000 字符 | — | 去除首尾空白后不能为空 |
size | 可选 | auto 或 宽x高 | — | 规则见表下 |
quality | 可选 | auto / low / medium / high | — | 2.5 与 2.6 另有 xhigh / max |
n | 可选 | integer,1–10 | 1 | 部分分组只支持 1 |
background | 可选 | auto / opaque / transparent | — | 透明需 png / webp |
output_format | 可选 | png / jpeg / webp;2.6 另有 svg / gif | png | 决定解码后的格式 |
output_compression | 可选 | integer,0–100 | 100 | 仅 jpeg / webp |
moderation | 可选 | auto / low | — | 不会关闭内容安全检查 |
user | 可选 | string | — | 终端用户标识 |
stream | 可选 | boolean | false | true 改为 Images SSE |
response_format | 可选 | string | — | 请省略 |
input_fidelity | 可选 | low / high | — | 兼容字段,请省略 |
complexity | 可选 | low / medium / high | high | 仅 2.6;出图前的规划强度 |
frame_count | 可选 | integer,2–16 | 9 | 仅 2.6 的 gif;帧数 |
frame_duration_ms | 可选 | integer,20–2,000 | 200 | 仅 2.6 的 gif;每帧毫秒数 |
size 的 宽x高 须为 16 的倍数,单边 ≤ 3840,长短边比 ≤ 3:1,总像素 655,360–8,294,400。不接受 1K / 2K / 4K 简写;不合规的 size 在生成前返回 400,不计费。
quality 越高,输出 token 越多、费用越高。response_format 传什么都以 b64_json 返回;user 不是 HopBase 账户 ID,也不改变计费归属。
仅 GPT Image 2.6。complexity 控制模型出图前做多少规划,不单独收费,写其他值返回 400。output_format: "svg" 返回 SVG,n 必须为 1。output_format: "gif" 返回 GIF 动图:此时 size 是单帧尺寸,所有帧会拼在一张边长不超过 3840 的图上,请用 auto 或 512x512 这类小尺寸(单帧太大会失败;GIF 单帧不受上面的总像素下限约束)。结果仍以 b64_json 返回,解码后存成 .svg 或 .gif。2.6 出的图带 OpenAI 的 C2PA 内容凭证,可用任意 C2PA 验证工具核验。
编辑
POST /v1/images/edits 接受上表全部参数,另加参考图与遮罩。推荐 multipart/form-data(本地文件),也接受 JSON(URL / Data URL)。
| 参数 | 必填 | 类型与限制 | 默认 | 说明 |
|---|---|---|---|---|
image | 必填 | 1–16 张 | — | multipart 用 image 或重复 image[] |
mask | 可选 | 带 alpha 通道的 PNG | — | 透明区域表示要编辑 |
markup | 可选 | 透明 PNG 叠加层 | — | 仅 2.6;按标注修改,不能与 mask 同用 |
JSON 的 image 可以是 URL / Data URL 字符串、字符串数组或 {"url": …} 对象。不读 images,不接受裸 base64 或 file_id。
**标注引导编辑(仅 GPT Image 2.6)。**在与第一张输入图同尺寸的透明 PNG 上画圈、箭头或写批注,作为 markup 传入:multipart 用文件字段,JSON 用 URL 或 Data URL。模型按标注修改,例如红圈加批注「在这里加一片绿叶」。markup 不能与 mask 同时使用;网关保留它的透明通道,并缩放到第一张图的尺寸。
远程 URL 单张 ≤ 25 MiB,Content-Type 须为 image/*,且不能指向内网地址;转发前可能压缩到 4 MiB。整个请求体上限 60 MB,超过返回 413。
异步
在生成或编辑请求上加 HTTP header Prefer: respond-async,请求体不变。它是 header,不是 JSON 参数。
异步任务只保留 model、prompt、n、size、quality、background、output_format、input_fidelity、complexity、frame_count、frame_duration_ms 和编辑用的图片 / mask / markup,其余字段丢弃。
返回结果
同步
| 字段 | 类型 | 说明 |
|---|---|---|
created | integer | Unix 秒 |
data[].b64_json | string | Base64 图片,解码后按 output_format 保存 |
usage.input_tokens | integer | 输入 token(可能返回) |
usage.output_tokens | integer | 输出 token(可能返回) |
usage.total_tokens | integer | 合计(可能返回) |
usage.cost | number | 本次扣费的人民币金额(与 usage.cost_usd 为同一笔扣费),最多 6 位小数。计费的同步成功响应都带 |
usage.cost_usd | number | 本次实际从余额扣除的美元金额,最多 8 位小数,与使用记录里这一条相同 |
usage.currency | string | usage.cost 的币种,恒为 CNY |
error | object | 失败时出现:message、type、code |
{
"created": 1760000000,
"data": [
{
"b64_json": "iVBORw0KGgoAAA..."
}
],
"usage": {
"input_tokens": 42,
"output_tokens": 1760,
"total_tokens": 1802,
"cost": 0.3264,
"cost_usd": 0.048,
"currency": "CNY"
}
}同步成功响应还带本次实际扣费:响应体的 usage.cost、usage.cost_usd 与 usage.currency,以及值相同的响应头 X-HopBase-Cost、X-HopBase-Cost-USD 与 X-HopBase-Currency。生成耗时较长(约 40 秒以上)、服务端已先发出 200 响应头保持连接时,响应头里没有扣费,请以响应体的 usage.cost_usd(美元,与使用记录一致)或 usage.cost(人民币)对账。未扣费的失败不带这些字段。详见扣费说明。
超过约 40 秒时,服务端先返回 HTTP 200,并在响应体开头持续写入空白保持连接,完整 JSON 稍后写完。此后即使生成失败,HTTP 状态仍是 200,请以响应体是否含 error 判断成败,读超时设为不少于 300 秒。
流式(stream: true)
响应改为 Images SSE:等待期间发送以冒号开头的 keepalive 注释行,最后一个 data: 事件才是完整的 Images JSON,并以 [DONE] 结束。这不是 OpenAI 原生的逐张预览事件。
: hopbase-keepalive
data: {"created":1760000000,"data":[{"b64_json":"iVBORw0KGgoAAA..."}]}
data: [DONE]异步任务
提交后立即返回 202 Accepted,响应头 Location 同样指向查询地址:
{
"object": "image.task",
"task_id": "你的task_id",
"status": "pending",
"status_url": "/v1/images/tasks?task_id=你的task_id"
}只能用 GET /v1/images/tasks?task_id=… 查询,不支持把任务 ID 放进路径。pending / processing / retrying 为进行中,终态是 completed 与 failed。
| 字段 | 类型 | 说明 |
|---|---|---|
task_id | string | 任务 ID |
status | string | 任务状态 |
result_content | string | 完成后出现:Markdown,每张图一行 |
error | string | 仅 failed 时出现,英文原因,无错误码 |
usage.cost | number | 本任务扣费的人民币金额(与 usage.cost_usd 为同一笔扣费) |
usage.cost_usd | number | 本任务实际从余额扣除的美元金额,与使用记录相同 |
usage.currency | string | usage.cost 的币种,恒为 CNY |
{
"task_id": "你的task_id",
"status": "completed",
"result_content": "",
"usage": {
"cost": 1.36,
"cost_usd": 0.2,
"currency": "CNY"
}
}result_content 里是相对路径,拼上 https://api.hop-base.com 即可下载。usage 在任务 completed 或 failed 后出现,只有创建任务的密钥能看到。
示例
生成
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-你的密钥" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.5-flare",
"prompt": "一只柴犬坐在樱花树下,日系水彩风格",
"size": "1024x1024",
"quality": "medium",
"output_format": "png"
}' \
| jq -r '.data[0].b64_json' | base64 --decode > result.pngcurl 示例需要先安装 jq。
SVG、GIF 动图与标注编辑(2.6)
# SVG(n 必须为 1)
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-你的密钥" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-flare",
"prompt": "一架纸飞机的扁平线条图标",
"output_format": "svg",
"complexity": "low"
}' \
| jq -r '.data[0].b64_json' | base64 --decode > icon.svg
# GIF 动图:size 是单帧尺寸
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-你的密钥" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-flare",
"prompt": "一只摇尾巴的柴犬,像素风",
"size": "512x512",
"output_format": "gif",
"frame_count": 9,
"frame_duration_ms": 200
}' \
| jq -r '.data[0].b64_json' | base64 --decode > shiba.gif# 标注引导编辑:markup.png 是画了标注的透明叠加层
curl https://api.hop-base.com/v1/images/edits \
-H "Authorization: Bearer sk-你的密钥" \
-F "model=gpt-image-2.6-flare" \
-F "prompt=按 markup 里的标注修改" \
-F "image=@plant.png" \
-F "markup=@markup.png" \
-F "output_format=png" \
| jq -r '.data[0].b64_json' | base64 --decode > edited.png编辑(多参考图 + 遮罩)
curl https://api.hop-base.com/v1/images/edits \
-H "Authorization: Bearer sk-你的密钥" \
-F "model=gpt-image-2.5-flare" \
-F "prompt=把遮罩区域换成一只花瓶,风格参考第二张图" \
-F "image[]=@scene.png" \
-F "image[]=@style.png" \
-F "mask=@mask.png" \
-F "size=1024x1024" \
-F "quality=high" \
-F "output_format=png"JSON 写法把文件换成 URL:"image": ["https://example.com/scene.png", "https://example.com/style.png"],"mask": "https://example.com/mask.png"。
异步
# 1. 提交后立即返回 202 + task_id
curl -i https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-你的密钥" \
-H "Content-Type: application/json" \
-H "Prefer: respond-async" \
-d '{
"model": "gpt-image-2",
"prompt": "电影感的未来城市夜景",
"size": "2048x2048"
}'
# 2. 用上一步的 task_id 轮询
curl "https://api.hop-base.com/v1/images/tasks?task_id=你的task_id" \
-H "Authorization: Bearer sk-你的密钥"注意事项
- 生成 2K / 4K 大图时建议用异步,避免长请求被 CDN 超时中断。
- 同步请求的客户端读超时设为不少于 300 秒。
size只收auto或宽x高,写档位简写返回 400。xhigh/max只有 2.5 与 2.6 的型号提供。complexity、markup、SVG / GIF 输出、frame_count、frame_duration_ms只有 2.6 两个型号提供。- GIF 输出请用
size: "auto"或512x512这类小尺寸,单帧尺寸太大会失败。 background: "transparent"需配合png或webp;gpt-image-2的透明背景属预览能力。- 不支持官方流式字段
partial_images(0–3),请省略。 - 使用官方 SDK 时请保持
stream为默认的false。 - 网关会把 mask 缩放到第一张参考图的尺寸,不保证遮罩外逐像素不变。
result_content的地址无需密钥即可打开,请勿公开分享,并尽快下载到自己的存储。
- 标准取值依据 OpenAI Images 文档与官方编辑规范。
output_compression、moderation、user、response_format只在同步 JSON 生成与同步 multipart 编辑中透传;JSON 编辑与异步任务不保留这些字段。n传更大值时,只支持 1 的分组返回 400;n≤ 0 按 1 处理。input_fidelity是兼容字段,GPT Image 2 默认高保真处理参考图。- 参考图张数由官方校验:网关不数张数,超出后可能被拒绝或只使用部分图片。
- 官方未明列所有参考图合计的 MB 上限;JSON 里单个 URL / Data URL 字符串最长 20,971,520 字符。
- 4 MiB 是转发前的压缩目标,不是上传拒绝门槛;Base64 编码会使数据量增加约 1/3。
- Data URL 示例:
data:image/png;base64,iVBORw0KGgo…,须是完整编码且 MIME 与图片匹配。 - 异步任务提交时只检查余额是否大于 0,不做金额预留。
常见报错
参数不合规在生成前返回 400,不计费。内容安全拦截也返回 400、不计费,error.code 为 safety_rejected。
| 报错 | 改法 |
|---|---|
size must be WIDTHxHEIGHT or auto 等 size 报错 | 按上方 size 规则修改 |
prompt must not be empty | 补上非空的 prompt |
n must be 1 for this model in the current group | 拆成多次请求 |
/v1/images/edits requires at least one image | 参考图放进 image,不要用 images |
image download returned HTTP 404 | 换成服务端能取得的公开 URL |
Your request was rejected by the safety system. | 改写提示词或更换参考图 |
Request body exceeds the size limit (60 MB)(413) | 压缩图片,或改传 URL |
HTTP 200 但响应体含 error | 保活开始后才失败,按 error.message 处理 |
# size: 按上表尺寸规则修改
size must be WIDTHxHEIGHT or auto
size side length exceeds 3840px (4096x2048)
size width and height must be multiples of 16 (1000x1000)
size aspect ratio must not exceed 3:1 (3840x1024)
size total pixel count must be at least 655360 (512x512=262144)
size total pixel count must not exceed 8294400 (3840x3840=14745600)
# prompt 为空
prompt must not be empty
# edits JSON: 参考图放在 "image",用字符串或 {"url": ...}
# 不读取 "images"
/v1/images/edits requires at least one image
image object is missing the url field
image must be a data URL or an http(s) URL
# 远程参考图:需为返回 image/* 的公开 URL,单张 ≤ 25 MiB
image download returned HTTP 404
image is too large
image Content-Type is not image/*: text/html
reference image URL must not point to an internal address
image is too large, please compress it to under 4MB and retry
# 内容安全拦截 (error.code: safety_rejected)
Your request was rejected by the safety system.
# HTTP 413
Request body exceeds the size limit (60 MB)计费
按 token 计费,quality 越高输出 token 越多:1024x1024 实测 low 约 200、high 约 1,760、xhigh 约 3,120、max 约 7,020 输出 token。GPT Image 2.6 低档输出更多:low 约 820、medium 约 1,450,所以 2.6 的 low / medium 比 2.5 贵,high 及以上相同。异步任务的实际扣费看查询结果的 usage.cost_usd(美元;usage.cost 为同一笔的人民币金额),失败通常为 0。同步请求的扣费直接看响应里的 usage.cost_usd / usage.cost。
单价见上表各模型卡与登录后的模型广场。
下一步
- 其他生图系列与选型见图片总览
- 其他系列:Gemini 生图、Seedream、Grok Imagine 生图、可灵生图、Midjourney
- 完整字段见 API 参考:生成图片、编辑图片、查询生图任务
- 报错时看报错速查