图片生成 API

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

端点一览

方法	路径	用途	请求格式
POST	`/v1/images/generations`	文生图	`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))

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。

HopBase 的 Azure Gemini 图片分组标准倍率为 3.1，按 ¥6.8/$ 折算约为官方基准 token 价的 45.6%；图片按实际 token 用量计费，最终以登录后模型广场为准。

Seedream 5.0 Pro · 文生图

BytePlus Seedream 5.0 Pro 的文生图走 /v1/images/generations，按输出张数计费、返回 24 小时有效的签名直链：

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[]=@./subject.png" \
  -F "image[]=@./style.png" \
  -F "size=2K" \
  -F "output_format=png"

Seedream 5.0 Pro 参数与计价

字段	说明
`model`	`seedream-5-0-pro`
`prompt`	图片内容、构图、风格或编辑指令；局部编辑可描述坐标、bbox、箭头或参考图中的涂画区域
`image`	可选；单个 URL / Data URL 或数组，最多 10 张。传入后触发单图 / 多图图生图或图片编辑
`size`	`1K` / `2K`，或总像素 921,600–4,624,220 且宽高比 1:16–16:1 的 `宽x高`；不支持 `4K`
`output_format`	`png` / `jpeg`
`optimize_prompt_options.mode`	可选；`standard` / `fast`
`response_format`	HopBase 目前使用 `url`，返回图片直链
官方基准价	只按输出图片计费：单张 ≤ 2.36MP（约 1K）$0.045 / 张；> 2.36MP（2K / 高像素自定义尺寸）$0.09 / 张；参考图不重复计费
HopBase 标准展示价	目前 68 折：单张 ≤ 2.36MP 为 $0.0306 / 张；> 2.36MP 为 $0.0612 / 张（USD 等值）

目前标准分组倍率为 4.624，模型广场按 ¥6.8/$ 折算成上面的 68 折 USD 等值；用户专属倍率与实际扣费以登录后模型广场为准。Seedream 支持同步文生图、单图 / 多图图生图与编辑，n=1、response_format=url；不支持图片异步任务、流式或 base64 响应。输入单张最多 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-5-0-pro 的 Seedream / Seedance 分组密钥；不要假设 OpenAI、Gemini 或 Claude 密钥可跨分组调用。

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

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

常用请求字段

字段	是否必填	说明
`model`	是	`gpt-image-2` 或当前密钥 `GET /v1/models` 返回的 Gemini Banana 图片模型 / `seedream-5-0-pro`
`prompt`	是	图片内容、构图、风格与文字要求
`size`	否	`auto` 或 `WIDTHxHEIGHT`；常用 1024×1024、1536×1024、1024×1536、2048×2048
`quality`	否	`low` / `medium` / `high` / `auto`
`n`	否	生成张数；部分模型目前只支持 1
`background`	否	`opaque` / `transparent`
`output_format`	否	`png` / `jpeg` / `webp`
`image` / `mask`	仅编辑必填 / 视模型而定	`/images/edits` 仅限支持编辑的模型，可传单张或多张参考图。Gemini 不接受 `mask`；Seedream 最多 10 张、单张最多 30 MB，也不接受传统 `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 Images 网关）

加入 HTTP header Prefer: respond-async 后，支持异步任务的模型会立即返回 202 Accepted、task_id 与 status_url，再由客户端轮询。任务状态为 pending / processing / completed / failed。完成后 result_content 会包含已存储图片的 Markdown URL。部分 Gemini 模型目前仍同步返回，请以实际 HTTP 状态码判断。

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

本页目录