图片生成 API

HopBase 对客户端统一提供 OpenAI Images 兼容协议。文生图发到 POST https://api.hop-base.com/v1/images/generations；即使模型是 Gemini Banana，也不要传 Gemini native generateContent payload，HopBase 会根据所选模型自动完成协议适配。

端点一览

方法	路径	用途	请求格式
POST	`/v1/images/generations`	文生图；Seedream 也用 `image` 做图生图 / 编辑	`application/json`
POST	`/v1/images/edits`	图生图 / 图片编辑	`multipart/form-data`（推荐）或 JSON（URL / Data URL）
GET	`/v1/images/tasks?task_id=…`	查询异步任务	加 `Prefer: respond-async` 时使用

所有端点都使用 Authorization: Bearer sk-你的密钥。Base URL 是 https://api.hop-base.com/v1。

文生图 · 最短可用 curl

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只柴犬坐在樱花树下，日系水彩风格",
    "size": "2048x2048",
    "quality": "medium",
    "background": "opaque",
    "output_format": "png",
    "n": 1
  }'

文生图 · OpenAI Python SDK

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://api.hop-base.com/v1",
    api_key="sk-你的密钥",
)

resp = client.images.generate(
    model="gpt-image-2",
    prompt="一只柴犬坐在樱花树下，日系水彩风格",
    size="2048x2048",
    quality="medium",
    background="opaque",
    output_format="png",
    n=1,
)

image = resp.data[0]
with open("result.png", "wb") as f:
    f.write(base64.b64decode(image.b64_json))

GPT Image 模型 ID

型号	模型 ID	定位
GPT Image 2	`gpt-image-2`	上一代；支持 `auto`、1K、2K、4K
GPT Image 2.5 Flare	`gpt-image-2.5-flare`	日常出图首选
GPT Image 2.5 Sunburst	`gpt-image-2.5-sunburst`	画质更强，同参数下比 Flare 略慢

两个 GPT Image 2.5 型号在 /v1/images/generations 与 /v1/images/edits 上使用同一套 OpenAI Images 协议，现有客户端只需把 model 换成新名字。价格见价格页与登录后模型广场。

GPT Image 2.5 参数

字段	GPT Image 2.5 行为
`size`	`1024x1024`、`1536x1024`、`1024x1536`、`auto`，或任意 `宽x高`：宽高须为 16 的倍数，最长边不超过 3840，宽高比在 1:3–3:1 之间（如 `1536x864`、`2048x1152`）。不合规会明确返回 400。
`quality`	`low` / `medium` / `high` / `xhigh` / `max` / `auto`。档位越高输出 token 越多、费用越高：1024x1024 实测 low 约 200、high 约 1,760、xhigh 约 3,120、max 约 7,020 输出 token。
`n`	单次可生成多张
`background`	`transparent` 需配合 `png` 或 `webp` 输出
`output_format` / `output_compression`	`png` / `jpeg` / `webp`，可指定压缩率
`moderation`	接受 `low`
`response_format`	传 `url` 会被接受，但图片仍以 `b64_json` 返回
图片编辑	支持单张参考图、多张参考图（重复传 `image[]`）以及带 alpha 通道的 `mask` 局部重绘：mask 透明区域重绘、不透明区域逐像素保留

参考耗时（单张 1024x1024）：low 档两个型号约 14 秒；high 档 Flare 约 19 秒、Sunburst 约 37 秒。

GPT Image 2.5 · 自定义尺寸文生图

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "石板上的陶瓷茶壶产品图，柔和的窗边光",
    "size": "2048x1152",
    "quality": "high",
    "output_format": "webp",
    "output_compression": 85
  }'

Gemini Banana 特殊兼容

能力	Gemini 兼容行为
请求入口	客户端统一调用 `/v1/images/generations`，HopBase 会根据所选模型自动完成请求适配。
响应	图片结果会统一为 OpenAI Images JSON，通常位于 `data[].b64_json`，也可能返回 `data[].url`。
图生图	支持图片编辑的 Gemini 模型可调用 `/v1/images/edits`，传入单张或多张参考图与自然语言指令；Gemini 不提供 `mask` 区域硬限制。
尺寸	`size` 会依所选模型预先校验，并在需要时自动适配尺寸要求。
其他参数	`quality`、`background`、`output_format`、`input_fidelity`、`n` 是否生效取决于具体模型能力，不能假设与 GPT Image 完全等价。
流式	Gemini 图片请使用默认同步模式，不要传 `"stream": true`；不支持流式输出的模型会明确返回错误。
异步	部分模型可使用 `Prefer: respond-async`；客户端应以实际 HTTP 状态码判断是否返回 `202 task_id`。

Gemini 所需的适配由 HopBase 在服务端自动完成；客户端的 Base URL、Bearer 密钥和 OpenAI Images 请求结构都不需要改。

Gemini Banana 图片模型 ID

系列	模型 ID	尺寸
Banana	`gemini-2.5-flash-image`	1K
Banana Pro	`gemini-3-pro-image` / `gemini-3-pro-image-c` `gemini-3-pro-image-preview` / `gemini-3-pro-image-preview-c`	1K / 2K / 4K
Banana 2	`gemini-3.1-flash-image` / `gemini-3.1-flash-image-c` `gemini-3.1-flash-image-preview` / `gemini-3.1-flash-image-preview-c`	1K / 2K
Banana 2 Lite	`gemini-3.1-flash-lite-image`	1K

-c 后缀在生产目录中是独立模型 ID，客户端调用协议与同系列 ID 相同。不要自行添加或移除后缀；接入前用当前密钥调 GET /v1/models，只使用实际回传的完整 ID。

Gemini 图片模型按实际 token 用量计费；不同套餐分组的折算倍率可能不同，最终以登录后模型广场为准。

Seedream 可用型号

型号	模型 ID	尺寸	输出 / 优化模式
Seedream 5.0 Pro	`seedream-5-0-pro`	1K / 1.5K / 2K	PNG / JPEG；standard / fast
Seedream 5.0 Lite（轻量版）	`seedream-5-0-lite`	2K / 3K / 4K	PNG / JPEG；standard
Seedream 4.5	`seedream-4-5`	2K / 4K	JPEG；standard

Lite 是 Seedream 5.0 的轻量版，公开模型名为 Seedream 5.0 Lite；请勿把 seedream-5-0-lite 当作 Pro 使用。价格见价格页与登录后的模型广场。💡 Pro 的 1.5K 与 1K 同价、生成效果更优，需要中小尺寸时建议优先 1.5K。⚠️ Lite 与 4.5 最小输出 2K（总像素 ≥ 3,686,400），需要 1K 小图请使用 Pro。

Seedream 5.0 Pro · 文生图

Seedream 文生图走 /v1/images/generations，按输出张数计费、返回 24 小时有效的签名直链。下面以 Pro 为例；也可换成当前密钥返回的 Lite 或 4.5 完整 ID，并遵循对应型号参数：

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "prompt": "霓虹夜色下的未来城市街景，电影感构图",
    "size": "2048x2048",
    "response_format": "url"
  }'

Seedream 5.0 Pro · 图生图 / 图片编辑（推荐 JSON）

仍调用 /v1/images/generations，增加 image 即可；可传 1–10 个 HTTP(S) URL 或图片 Data URL。单图、多图融合、参考图重绘及带坐标 / bbox / 箭头 / 涂画标注的局部编辑都使用这个入口：

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "prompt": "把第一张图中的杯子移到桌面右侧，保持其余内容不变",
    "image": ["https://example.com/source.png"],
    "size": "2K",
    "output_format": "png",
    "response_format": "url"
  }'

Seedream 5.0 Pro · OpenAI edits 兼容入口（本机文件）

已有 OpenAI Images 编辑代码时，可直接使用 /v1/images/edits 的 multipart 格式；HopBase 会自动完成文件与请求格式适配：

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-你的密钥" \
  -F "model=seedream-5-0-pro" \
  -F "prompt=根据两张参考图重新设计海报，保留主体与品牌配色" \
  -F "image[][email protected]" \
  -F "image[][email protected]" \
  -F "size=2K" \
  -F "output_format=png"

Seedream 共通参数

字段	说明
`model`	使用当前密钥 `GET /v1/models` 返回的 Seedream 完整 ID
`prompt`	图片内容、构图、风格或编辑指令；局部编辑可描述坐标、bbox、箭头或参考图中的涂画区域
`image`	可选；单个 URL / Data URL 或数组。上限：Pro 10 张，Lite / 4.5 为 14 张。传入后触发单图 / 多图图生图或图片编辑
`size`	按上表选择简写尺寸；自定义 `宽x高` 宽高比 1:16–16:1。总像素范围：Pro 为 921,600–4,624,220；Lite / 4.5 为 3,686,400–16,777,216（低于下限会被网关直接拒绝并提示合法区间）
`output_format`	Pro / Lite：`png` 或 `jpeg`；4.5：仅 `jpeg`
`optimize_prompt_options.mode`	Pro：`standard` / `fast`；Lite / 4.5：仅 `standard`
`response_format`	HopBase 目前使用 `url`，返回图片直链

实际倍率与扣费以登录后模型广场为准。Seedream 支持同步文生图、单图 / 多图图生图与编辑，n=1、response_format=url；不支持图片异步任务或流式。输入单张最多 30 MB / 36MP，可用 JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC、HEIF。⚠️ 返回的 URL 是 24 小时有效的签名直链，请及时下载留存。

Seedream 的局部编辑不是传统 mask 硬遮罩：请把标注直接画在参考图上，并在 prompt 中描述坐标 / bbox / 箭头 / 涂画区域。/v1/images/edits 若传 mask 会明确返回 400，避免产生错误语义。

✅ 请使用能在 GET /v1/models 返回目标 Seedream 完整 ID 的分组密钥；不要假设其他分组密钥可以调用这些模型。

通用图生图 / 图片编辑 · multipart curl

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-你的密钥" \
  -F "model=gpt-image-2" \
  -F "prompt=把参考图改成梵高星空风格的油画" \
  -F "[email protected]" \
  -F "size=1536x1024" \
  -F "quality=medium" \
  -F "output_format=png"

GPT Image 2.5 · 多参考图 + mask 局部重绘

mask 为带 alpha 通道的 PNG：透明像素按 prompt 重绘，不透明像素原样保留。多张参考图重复传 image[] 即可。

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"

常用请求字段

字段	是否必填	说明
`model`	是	`gpt-image-2`、`gpt-image-2.5-flare`、`gpt-image-2.5-sunburst`，或当前密钥 `GET /v1/models` 返回的 Gemini Banana / Seedream 图片模型完整 ID
`prompt`	是	图片内容、构图、风格与文字要求
`size`	否	`auto` 或 `WIDTHxHEIGHT`；常用 1024×1024、1536×1024、1024×1536、2048×2048；GPT Image 2.5 另支持上文规则内的自定义尺寸
`quality`	否	`low` / `medium` / `high` / `auto`；GPT Image 2.5 另接受 `xhigh` / `max`
`n`	否	生成张数；部分模型目前只支持 1
`background`	否	`opaque` / `transparent`
`output_format`	否	`png` / `jpeg` / `webp`
`image` / `mask`	仅编辑必填 / 视模型而定	`/images/edits` 仅限支持编辑的模型，可传单张或多张参考图。Gemini 不接受 `mask`；Seedream 最多 10 张、单张最多 30 MB，也不接受传统 `mask`。GPT Image 2.5 支持重复传 `image[]` 多参考图与带 alpha 通道的 `mask`。

图片尺寸会按模型先做校验；模型不支持的 2K / 4K 尺寸会直接返回 400，不会产生图片生成费用。

同步响应（默认）

不传 Prefer 时会等待图片完成，返回标准 OpenAI Images JSON。图片通常位于 data[].b64_json，部分模型可能返回 data[].url；usage 提供 token 用量。

{
  "created": 1780000000,
  "data": [{
    "b64_json": "iVBORw0KGgoAAA...",
    "revised_prompt": "..."
  }],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 1056,
    "total_tokens": 1074
  }
}

⚠️ 支持流式输出的非 Gemini 图片模型传 "stream": true 时会改为 SSE，期间发送 keepalive ping，最后一个 data: 事件才是 Images JSON，并以 [DONE] 结束。Gemini 图片不支持这套 Images SSE 语义；使用官方 SDK 时建议一律保持默认同步模式。

异步任务模式（OpenAI / Gemini Images 网关）

加入 HTTP header Prefer: respond-async 后，支持异步任务的模型会立即返回 202 Accepted、task_id 与 status_url，再由客户端轮询。任务状态为 pending / processing / completed / failed。完成后 result_content 会包含已存储图片的 Markdown URL。Gemini 图片模型亦已支持异步任务；生成 2K / 4K 大图时建议优先使用，可避免长时间请求被 CDN 超时中断。

# 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-你的密钥"

本页目录