跳到正文
HopBase 文档
登录控制台

生成图片

OpenAI Images 兼容的文生图：GPT Image、Gemini Banana 与 Seedream；Seedream 与 Gemini 也在这里传参考图。

POST/v1/images/generations

按提示词生成图片。GPT Image 与 Gemini 返回 data[].b64_json，Seedream 返回 data[].url（24 小时有效）。Seedream 与两个 Gemini 分组也在这个端点用 image / images 做图生图。

每个模型的参数与上限不同：在下方选择模型，参数表随之切换，数字取自插件校验代码导出的规格（与 /spec/models/<model>.json 同源）。GPT Image 生成超过约 40 秒时服务端先回 200 并写空白保活，此后失败也仍是 200——请以响应体是否含 error 判断成败，客户端读超时不少于 300 秒。

可灵与 Midjourney 也在这个端点提交，但一律异步（202 + id，用查询视频任务轮询），在模型选择里选「可灵」「Midjourney」查看；Grok Imagine 见 Grok Imagine 生图。

  • GPT Image 不支持官方流式字段 partial_images，请省略；stream: true 返回的是 HopBase Images SSE，不是逐张预览事件。
  • output_compression、moderation、user、response_format 只在同步文生图 JSON 与同步 multipart 编辑中透传；JSON 编辑与异步任务不保留这些字段。GPT Image 异步只保留 model、prompt、n、size、quality、background、output_format、input_fidelity 和编辑用的图片 / mask。
  • Gemini 计费：「Gemini 全系（含生图）」按张计费，1K / 2K / 4K 同价；「Gemini 官方直连」按 token 计费（输出 token × 单价）。
  • Chat Completions 转 Images 的桥接路径只保留前 6 张参考图；要用 14 张请直接调本端点。

请求头

Authorization:必填string

Bearer sk-…：控制台「API 密钥」里创建的密钥，所属分组须包含请求的模型

Prefer:可选string

respond-async：GPT Image / Gemini 立即返回 202 Accepted、task_id 与 status_url，再用 GET /v1/images/tasks?task_id=… 轮询。生成 2K / 4K 大图时建议使用；Seedream 忽略此头、照常同步返回

可选值respond-async

请求体参数JSON

模型在图片请求构建器中打开 模型文档
分组：GPT Image 全系。 结果读 data[].b64_json。 参考图最多 16 张。
model:必填"gpt-image-2"

先确认当前密钥的 GET /v1/models 包含此 ID

prompt:必填string

生成或编辑指令；为空返回 400 prompt must not be empty。网关不限长度，上限为官方上限

限制去除首尾空白后不能为空，否则 400「prompt must not be empty」长度1–32000 字符

size:可选"auto" 或 string

例：1024x1024、2048x2048、3840x2160。不合规在生成前返回 400、不计费；不接受 1K / 2K / 4K

限制auto 或 宽x高：边长为 16 的倍数、单边 ≤ 3840、长短边比 ≤ 3:1、总像素 655360–8294400

quality:可选string

档位越高输出 token 越多、费用越高：1024x1024 实测 low 约 200、high 约 1,760、xhigh 约 3,120、max 约 7,020 输出 token

可选值autolowmediumhigh

限制网关不校验、原样转发；档位越高输出 token 越多

n:可选integer

部分分组只支持 1，传更大值返回 400；≤ 0 按 1 处理

范围1–10默认1

background:可选string

transparent 需配合 png 或 webp；2.0 透明背景属预览能力

可选值autoopaquetransparent

output_format:可选string

决定 b64_json 解码后的格式

可选值pngjpegwebp

output_compression:可选integer

仅 jpeg / webp；只在同步 generations JSON 与 multipart 编辑中保留

范围0–100默认100

moderation:可选string

不会关闭内容安全检查

可选值autolow

user:可选string

终端用户识别字符串，不是 HopBase 账户 ID，也不改变计费归属

response_format:可选string

传什么都以 b64_json 返回，不能靠 url 取得下载链接，请省略

限制传什么都以 b64_json 返回，请省略

stream:可选boolean

true 改为 HopBase Images SSE（期间发送 keepalive，最后一个 data: 事件才是 Images JSON，以 [DONE] 结束），不是 OpenAI 原生逐张预览事件；SDK 请保持 false

限制true 返回 HopBase Images SSE，SDK 请保持 false默认false

input_fidelity:可选string

兼容字段；GPT Image 2 默认高保真处理参考图，请省略

可选值lowhigh

  • transparent 需要 png 或 webp
  • output_compression 只对 jpeg / webp 生效

返回

200同步成功

202异步受理：GPT Image / Gemini 带 Prefer: respond-async 时；可灵与 Midjourney 一律如此

created:可选integer

Unix 秒

data:必填array of object

每张图一项

usage:可选object

可能返回

错误

400参数不合规（生成前拒绝，不计费）；内容安全拦截 safety_rejected
401没带密钥、密钥无效或已过期（missing_api_key / invalid_api_key / api_key_expired）
402余额或密钥 / 成员 / 部门额度用完（insufficient_quota）
404模型不在这把密钥的分组里（model_not_found），或路径不属于该分组（route_not_found）
413请求体超过 60 MB（request_too_large）
429帐户或密钥并发已达上限（user_concurrency_limit / apikey_concurrency_limit），带 Retry-After
GPT Image 报错原文
# 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)
Gemini 报错原文
# 「Gemini 全系（含生图）」
prompt must not be empty
n must be between 1 and 10 for model gemini-3-pro-image
n=3 is too large for 4K output on model gemini-3-pro-image; at most 2 images per request at this size (response size limit); lower n or send separate requests
model gemini-3.1-flash-image does not support tier 4K; supported: 1K, 2K
model gemini-3-pro-image: size "big" is not valid; expected WIDTHxHEIGHT (any aspect ratio, mapped to the nearest official tier) or 1K/2K/4K
aspect_ratio "7:3" is not supported for model gemini-3-pro-image; allowed values: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
image_size "4K" is not supported for model gemini-3.1-flash-image; supported: 1K, 2K
background=transparent is not supported for model gemini-3-pro-image; Gemini image models cannot output transparent images
mask is not supported for Gemini image models; remove mask and describe the region to edit in the prompt
too many reference images: at most 14 are supported for this model, got 15

# 「Gemini 官方直连」
missing prompt
Gemini image generation does not support stream=true; send a non-streaming request
n must be at most 10
n=6 is too large for 2K output on model gemini-3.1-flash-image; at most 5 images per request at this size (response size limit); lower n or send separate requests
Images generations only accepts a JSON request body: ...
size 4K is not supported for model gemini-3.1-flash-image; supported tiers: 1K, 2K
size "banana" is not valid for model gemini-3-pro-image; use auto, WIDTHxHEIGHT (e.g. 1024x1024, mapped to the nearest supported aspect ratio and capped at the model's largest tier), or one of: 1K, 2K, 4K
image_config.aspect_ratio "7:3" is not supported; allowed values: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
image_config.image_size "4K" is not supported for model gemini-3.1-flash-image; allowed values: 1K, 2K
mask is not supported for model gemini-3-pro-image; remove mask and describe the region to edit in the prompt
background=transparent is not supported for model gemini-3-pro-image; Gemini image models cannot output transparent images
reference image 1: reference image exceeds the 20MB limit
reference image 1: reference image URL must not point to an internal address
reference image 1: reference image download returned HTTP 404
reference image 1: reference file is not a supported image type
Seedream 报错原文
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size   # 例如 "size": "auto"
model seedream-5-0-lite requires the total pixel count of size to be between 3686400 and 16777216
size aspect ratio must be between 1:16 and 16:1
missing prompt
response_format only supports url
only a single output is supported (n=1)
model seedream-4-5 only supports output_format jpeg
optimize_prompt_options must be an object
image must be a URL/data URL string or an array of strings
every item in the image array must be a URL or data URL string
image must not be empty
at most 10 reference images are supported
reference image 1 is invalid: data URL must be base64-encoded
reference image 1 is invalid: unsupported image format image/svg+xml
reference image 1 is invalid: a single image must not exceed 30 MB
image edits require at least one image reference            # /v1/images/edits 未带图
seedream does not accept a traditional mask; ...            # /v1/images/edits 带 "mask" 即拒，null 也一样

相关页面