GPT Image

默认同步返回 Base64 图片，加 Prefer: respond-async 可改为异步任务；对话分组的密钥调 gpt-image-* 会返回 404。

可用型号

选型建议：日常出图首选 Flare；要画质选 Sunburst，同参数下比 Flare 略慢；gpt-image-2 是通用型号，ID 是 gpt-image-2，不是 gpt-image-2.0。参考耗时（单张 1024x1024）：low 档 2.5 两个型号约 14 秒，high 档 Flare 约 19 秒、Sunburst 约 37 秒。

请求参数

生成

POST /v1/images/generations，JSON 请求体。

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，也不改变计费归属。

编辑

POST /v1/images/edits 接受上表全部参数，另加参考图与遮罩。推荐 multipart/form-data（本地文件），也接受 JSON（URL / Data URL）。

JSON 的 image 可以是 URL / Data URL 字符串、字符串数组或 {"url": …} 对象。不读 images，不接受裸 base64 或 file_id。

远程 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 和编辑用的图片 / mask，其余字段丢弃。

返回结果

同步

{
  "created": 1760000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAA..."
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1760,
    "total_tokens": 1802
  }
}

流式（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": "你的task_id",
  "status": "completed",
  "result_content": "![image](/assets-runtime/2026/09/xxxxxxxxxxxx.png)",
  "usage": {
    "cost": 1.36,
    "currency": "CNY",
    "cost_cny": 1.36,
    "cost_usd": 0.2
  }
}

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。

编辑（多参考图 + 遮罩）

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-你的密钥" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=把遮罩区域换成一只花瓶，风格参考第二张图" \
  -F "image[][email protected]" \
  -F "image[][email protected]" \
  -F "[email protected]" \
  -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 两个型号提供。
• background: "transparent" 需配合 png 或 webp；gpt-image-2 的透明背景属预览能力。
• 不支持官方流式字段 partial_images（0–3），请省略。
• 使用官方 SDK 时请保持 stream 为默认的 false。
• 网关会把 mask 缩放到第一张参考图的尺寸，不保证遮罩外逐像素不变。
• result_content 的地址无需密钥即可打开，请勿公开分享，并尽快下载到自己的存储。

常见报错

参数不合规在生成前返回 400，不计费。内容安全拦截也返回 400、不计费，error.code 为 safety_rejected。

# 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。异步任务的实际扣费看查询结果的 usage.cost（cost_cny / cost_usd 按固定 1 USD = 6.8 CNY 换算），失败通常为 0。

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

下一步

• 其他生图系列与选型见图片总览
• 其他系列：Gemini 生图、Seedream、Grok Imagine 生图、可灵生图、Midjourney
• 完整字段见 API 参考：生成图片、编辑图片、查询生图任务
• 报错时看报错速查