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

Gemini 生图

用 Gemini 生成和编辑图片：参数、返回与注意事项。

项目值
Base URLhttps://api.hop-base.com/v1
生成（含参考图编辑）POST /v1/images/generations
编辑（仅「Gemini 全系（含生图）」）POST /v1/images/edits
查询异步任务GET /v1/images/tasks?task_id=…
密钥分组「Gemini 全系（含生图）」或「Gemini 官方直连」

Gemini 生图（昵称 Banana）使用 OpenAI Images 接口，同步返回 Base64 图片，两个分组的编辑入口与计费方式不同。

可用型号

型号模型 ID尺寸档位官方价
Gemini 3 Pro Image（Banana Pro）gemini-3-pro-image1K / 2K / 4K$0.1344起/ 张
Gemini 3.1 Flash Image（Banana 2）gemini-3.1-flash-image1K / 2K$0.0672/ 张
Banana 2 预览版gemini-3.1-flash-image-preview1K / 2K$0.0672/ 张
Gemini 3.1 Flash Lite Image（Banana 2 Lite）gemini-3.1-flash-lite-image1K$0.0336/ 张
Gemini 2.5 Flash Image（Banana）gemini-2.5-flash-image1K$0.0387/ 张

选型建议：要 4K 只能用 gemini-3-pro-image；gemini-3.1-flash-image 的 1K 与 2K 同价；多参考图合成不要用 Lite，它未针对多参考图优化。

两个分组的差异：

分组/v1/images/edits计费
Gemini 全系（含生图）支持按交付张数
Gemini 官方直连返回 404，参考图放在 generations按 token

「Gemini 官方直连」还能在 /v1/chat/completions 里调用图片模型，图片以 markdown 内嵌 data URL 返回。

请求参数

生成

POST /v1/images/generations，JSON 请求体。请求体用 OpenAI Images 结构，不要传 Gemini 原生 generateContent 结构。

参数必填类型与限制默认说明
model必填字符串，见上表—以当前密钥 GET /v1/models 的返回为准
prompt必填字符串，去除首尾空白后非空—生成或编辑指令
size可选auto、任意比例的 宽x高，或 1K / 2K / 4K—换算成比例与档位，见下文
n可选整数 1–101另按档位封顶，见下文
google.image_config.aspect_ratio可选10 个官方比例1:1优先于 size
google.image_config.image_size可选型号档位内的 1K / 2K / 4K1K优先于 size
image / images可选URL / Data URL，字符串或字符串数组—参考图，同时传时以 images 为准
quality、response_format、output_format可选任意—传了不生效

aspect_ratio 可选值：1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 4:5 / 5:4 / 9:16 / 16:9 / 21:9。

image_config 有三种等价写法，同时出现时按下面的顺序取第一个：

  • google.image_config
  • extra_body.google.image_config（OpenAI SDK 的写法）
  • 顶层扁平的 aspect_ratio / image_size

显式写出超过型号档位的 image_size 返回 400。

size 写 宽x高 时从不因比例被拒：映射到最接近的官方比例，档位按长边推导，并静默降到型号最高档位、不报错。

例如 gemini-3.1-flash-image 传 4096x4096 返回 2K 图。档位简写超出型号档位时则返回 400。

n 另按输出档位封顶：4K ≤ 2、2K ≤ 5、1K ≤ 10（响应体积上限），超出返回 400。

参考图

两个分组都在 generations 的 image / images 里传参考图，仅限 JSON。每项是 http(s) URL 或 Data URL 字符串，URL 须能被服务端取得，不能指向内网地址。

分组数量单张大小
Gemini 全系（含生图）最多 14 张，超出返回 400远程 URL ≤ 25 MiB
Gemini 官方直连官方上限 14 张，网关不校验解码后 ≤ 20 MiB

「Gemini 全系（含生图）」会把超过 4 MiB 的参考图自动压缩后再生成。gemini-2.5-flash-image 官方最多 3 张参考图。Data URL 示例：data:image/png;base64,iVBORw0KGgo…，MIME 须与图片一致。

编辑（仅「Gemini 全系（含生图）」）

POST /v1/images/edits 推荐 multipart/form-data，也接受 JSON（参考图为 URL / Data URL）。至少要带 1 张参考图。

参数必填类型与限制默认说明
image / image[]必填文件或 URL 字符串，可重复—参考图
model、prompt必填同「生成」——
size、n可选同「生成」——
aspect_ratio、image_size可选同「生成」的 image_config—multipart 字段名

「Gemini 官方直连」没有这个端点，调用返回 404；改图请在 generations 里带参考图。两个分组都不支持 mask，传入返回 400。

异步

加 HTTP header Prefer: respond-async 后，立即返回 202 Accepted 与 task_id。生成 2K / 4K 大图时建议使用，可避免长请求被 CDN 超时中断。

返回结果

同步返回 OpenAI Images JSON，图片在 data[].b64_json。

字段类型说明
createdintegerUnix 秒
modelstring请求的模型 ID
data[].b64_jsonstringBase64 图片数据
data[].mime_typestring图片格式，可能是 image/jpeg
usageobject可能返回，含输入、输出与总 token
usageMetadataobject「Gemini 官方直连」可能返回，Gemini 官方用量字段
{
  "created": 1760000000,
  "model": "gemini-3-pro-image",
  "data": [
    {
      "b64_json": "/9j/4AAQSkZJRgABAQ...",
      "mime_type": "image/jpeg"
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1120,
    "total_tokens": 1162
  }
}

异步任务

提交后立即返回：

{
  "task_id": "imgtask_EXAMPLE",
  "status": "pending",
  "status_url": "/v1/images/tasks?task_id=imgtask_EXAMPLE"
}
只能用查询参数 task_id 查询，不支持把任务 ID 放进路径。
状态含义
pending / processing / retrying进行中，继续轮询
completed完成，读 result_content
failed失败，只返回 error 字符串，没有错误码

完成后的响应：

{
  "task_id": "imgtask_EXAMPLE",
  "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 每张图一行 ![image](/assets-runtime/…)，是相对路径，需自行拼上 https://api.hop-base.com。该地址无需密钥即可打开，请勿公开分享，并尽快下载到自己的存储。

示例

文生图

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "洒满阳光的木桌上放着一只陶瓷茶壶，产品摄影",
    "google": {
      "image_config": { "aspect_ratio": "16:9", "image_size": "2K" }
    }
  }' \
  | jq -r '.data[0].b64_json' | base64 --decode > result.png

curl 示例需要先安装 jq。若 data[].mime_type 是 image/jpeg，请把扩展名改为 .jpg。

参考图编辑

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "把第一张图的杯子换成第二张图的配色，其余不变",
    "images": [
      "https://example.com/cup.png",
      "https://example.com/palette.png"
    ],
    "size": "1024x1024"
  }'

注意事项

  • 只有「Gemini 全系（含生图）」提供 /v1/images/edits，另一个分组请在 generations 里传参考图。
  • 结果是 Base64，可能是 JPEG，保存前请看 data[].mime_type。
  • 不支持 mask，局部修改请在 prompt 中描述区域。
  • 不能输出透明背景，background: "transparent" 返回 400。
  • 不支持 stream: true，请保持默认同步或使用异步任务。
  • 2K / 4K 大图建议加 Prefer: respond-async，同步请求的客户端读超时请设长一些。
  • 发付费请求前用实际密钥调 GET /v1/models 取完整 ID，不要自己加档位后缀。

常见报错

参数不合规在生成前返回 400，不计费。

报错改法
prompt must not be empty / missing prompt补上非空的 prompt
n=3 is too large for 4K output on model gemini-3-pro-image; …调小 n 或分开请求
model gemini-3.1-flash-image does not support tier 4K; supported: 1K, 2K换用 gemini-3-pro-image 或降档
aspect_ratio "7:3" is not supported for model …改用官方比例
mask is not supported for Gemini image models; …去掉 mask，在 prompt 中描述区域
background=transparent is not supported …去掉 background
Gemini image generation does not support stream=true; …去掉 stream
too many reference images: at most 14 are supported …减少参考图
reference image 1: reference image exceeds the 20MB limit压缩图片后重试
reference image 1: reference image download returned HTTP 404换成服务端能取得的公开 URL
400（引用模型文字）或 502模型拒答或只回文字，请改写提示词

计费

「Gemini 全系（含生图）」按实际交付张数计费；「Gemini 官方直连」按 token 计费，按实际生成的档位计。参数错误与部分失败不计费；异步任务终态后，查询响应的 usage.cost 是实际扣费。

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

下一步

本页目录

可用型号请求参数生成参考图编辑（仅「Gemini 全系（含生图）」）异步返回结果异步任务示例文生图参考图编辑注意事项常见报错计费下一步