跳到正文

GPT Image

用 GPT Image 生成和编辑图片:参数、返回与注意事项。

项目值
Base URLhttps://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。

可用型号

型号模型 IDquality 档位官方价
GPT Image 2.6 Flaregpt-image-2.6-flarelow / medium / high / xhigh / max$5 / $30/ 百万 tokens
GPT Image 2.6 Sunburstgpt-image-2.6-sunburstlow / medium / high / xhigh / max$5 / $30/ 百万 tokens
GPT Image 2.5 Flaregpt-image-2.5-flarelow / medium / high / xhigh / max$5 / $30/ 百万 tokens
GPT Image 2.5 Sunburstgpt-image-2.5-sunburstlow / medium / high / xhigh / max$5 / $30/ 百万 tokens
GPT Image 2gpt-image-2low / 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–101部分分组只支持 1
background可选auto / opaque / transparent—透明需 png / webp
output_format可选png / jpeg / webp;2.6 另有 svg / gifpng决定解码后的格式
output_compression可选integer,0–100100仅 jpeg / webp
moderation可选auto / low—不会关闭内容安全检查
user可选string—终端用户标识
stream可选booleanfalsetrue 改为 Images SSE
response_format可选string—请省略
input_fidelity可选low / high—兼容字段,请省略
complexity可选low / medium / highhigh仅 2.6;出图前的规划强度
frame_count可选integer,2–169仅 2.6 的 gif;帧数
frame_duration_ms可选integer,20–2,000200仅 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,其余字段丢弃。

返回结果

同步

字段类型说明
createdintegerUnix 秒
data[].b64_jsonstringBase64 图片,解码后按 output_format 保存
usage.input_tokensinteger输入 token(可能返回)
usage.output_tokensinteger输出 token(可能返回)
usage.total_tokensinteger合计(可能返回)
usage.costnumber本次扣费的人民币金额(与 usage.cost_usd 为同一笔扣费),最多 6 位小数。计费的同步成功响应都带
usage.cost_usdnumber本次实际从余额扣除的美元金额,最多 8 位小数,与使用记录里这一条相同
usage.currencystringusage.cost 的币种,恒为 CNY
errorobject失败时出现: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 秒:状态码仍是 200,请读 error 字段:

超过约 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_idstring任务 ID
statusstring任务状态
result_contentstring完成后出现:Markdown,每张图一行
errorstring仅 failed 时出现,英文原因,无错误码
usage.costnumber本任务扣费的人民币金额(与 usage.cost_usd 为同一笔扣费)
usage.cost_usdnumber本任务实际从余额扣除的美元金额,与使用记录相同
usage.currencystringusage.cost 的币种,恒为 CNY
{
  "task_id": "你的task_id",
  "status": "completed",
  "result_content": "![image](/assets-runtime/2026/09/xxxxxxxxxxxx.png)",
  "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.png

curl 示例需要先安装 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 的地址无需密钥即可打开,请勿公开分享,并尽快下载到自己的存储。

常见报错

参数不合规在生成前返回 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 处理

计费

按 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。

单价见上表各模型卡与登录后的模型广场。

下一步