Gemini · OpenAI 兼容协议

如果你的项目已经使用 OpenAI SDK、/v1/images/generations 或 /v1/images/edits，可以直接通过知梦的 OpenAI 兼容协议调用 Banana 2 / Banana 2.1 / Banana Pro。

快速信息

项目	内容
REST Base URL	`https://api.zmoapi.cn`
SDK Base URL	`https://api.zmoapi.cn/v1`
协议	OpenAI 兼容图片协议
文生图	`POST /v1/images/generations`
本地图片编辑	`POST /v1/images/edits`
返回图片	`data[].url`

1. 鉴权

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

OpenAI SDK：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ZHM_API_KEY,
  baseURL: "https://api.zmoapi.cn/v1"
});

2. 模型 ID

分辨率由模型名后缀决定：

模型 ID	模型	输出档位	价格
`banana2-1k`	Banana 2	1K	¥0.08 / 张
`banana2-2k`	Banana 2	2K	¥0.08 / 张
`banana2-4k`	Banana 2	4K	¥0.08 / 张
`nano-banana-2.1-1k`	Banana 2.1	1K	¥0.06 / 张
`nano-banana-2.1-2k`	Banana 2.1	2K	¥0.06 / 张
`nano-banana-2.1-4k`	Banana 2.1	4K	¥0.06 / 张
`banana-pro-1k`	Banana Pro	1K	¥0.09 / 张
`banana-pro-2k`	Banana Pro	2K	¥0.09 / 张
`banana-pro-4k`	Banana Pro	4K	¥0.09 / 张

分辨率由模型 ID 决定

需要 4K 时请选择 banana2-4k、nano-banana-2.1-4k 或 banana-pro-4k。不要只修改 size 就期待 1K 模型变成 4K。

Banana 2.1

Banana 2.1 沿用 Banana 2 / Banana Pro 的请求参数、URL / Base64 参考图、本地文件 multipart 编辑和响应处理方式。使用本页后续示例时，将 model 替换为所需的 nano-banana-2.1-1k、nano-banana-2.1-2k 或 nano-banana-2.1-4k 即可；三个档位均为 ¥0.06 / 张。size 仍填写画面比例，分辨率由模型 ID 的后缀决定。

以下为 2K 文生图示例：

bash

curl 'https://api.zmoapi.cn/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "model": "nano-banana-2.1-2k",
    "prompt": "生成一张现代科技产品宣传图，主体居中，光线干净，画面精致",
    "size": "16:9",
    "response_format": "url",
    "n": 1
  }'

在线调试 Banana 2.1 · OpenAI 协议 →

3. 文生图

接口：

http

POST /v1/images/generations

cURLJavaScriptPython

bash

curl 'https://api.zmoapi.cn/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "model": "banana2-2k",
    "prompt": "生成一张现代科技产品宣传图，主体居中，光线干净，画面精致",
    "size": "16:9",
    "response_format": "url",
    "n": 1
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ZHM_API_KEY,
  baseURL: "https://api.zmoapi.cn/v1"
});

const result = await client.images.generate({
  model: "banana2-2k",
  prompt: "生成一张简洁精致的产品海报",
  size: "16:9",
  response_format: "url"
});

console.log(result.data[0].url);

python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.zmoapi.cn/v1",
)

result = client.images.generate(
    model="banana2-2k",
    prompt="生成一张简洁精致的产品海报",
    size="16:9",
    response_format="url",
)

print(result.data[0].url)

4. 常用请求字段

字段	类型	说明
`model`	string	必填，使用 `banana2-`、`nano-banana-2.1-` 或 `banana-pro-*`
`prompt`	string	必填，生成或编辑要求
`size`	string	宽高比 / 客户端尺寸参数，例如 `1:1`、`16:9`、`9:16`
`resolution`	string	兼容字段，可写 `1K` / `2K` / `4K`；最终档位仍以模型后缀为准
`aspect_ratio`	string	宽高比兼容字段；不要与 `size` 传冲突值
`n`	number	生成数量；通常建议 `1`
`response_format`	string	推荐 `url`
`stream`	boolean	`true` 时使用 SSE 实时状态
`user`	string	可选的业务用户标识

5. URL 参考图（JSON）

参考图可直接放在 JSON 里。多图顺序就是数组顺序，建议提示词明确说明每张图的用途。

`images`

bash

curl 'https://api.zmoapi.cn/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "model": "banana-pro-4k",
    "prompt": "第一张图是商品主体，第二张图是目标场景。保持商品结构不变，将商品自然放入目标场景。",
    "size": "16:9",
    "response_format": "url",
    "images": [
      "https://example.com/product.png",
      "https://example.com/scene.jpg"
    ]
  }'

`image_urls`

json

{
  "model": "banana2-2k",
  "prompt": "参考这些图片生成一张统一风格的商品海报",
  "aspect_ratio": "4:5",
  "response_format": "url",
  "image_urls": [
    "https://example.com/product.png",
    "data:image/jpeg;base64,BASE64_IMAGE_DATA"
  ]
}

对于单张参考图，也可兼容 image / image_url。多图建议统一使用 images 或 image_urls。

6. 本地文件参考图 / 图片编辑

本地文件直接上传使用：

http

POST /v1/images/edits
Content-Type: multipart/form-data

单图

bash

curl 'https://api.zmoapi.cn/v1/images/edits' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'model=banana2-2k' \
  -F 'prompt=保留商品主体和文字，将背景改成明亮的室内展厅' \
  -F 'size=16:9' \
  -F 'response_format=url' \
  -F 'image=@./product.png'

多图

bash

curl 'https://api.zmoapi.cn/v1/images/edits' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'model=banana-pro-4k' \
  -F 'prompt=第一张为人物参考，第二张为服装参考，第三张为背景参考，生成一张9:16海报' \
  -F 'aspect_ratio=9:16' \
  -F 'response_format=url' \
  -F 'image=@./person.png' \
  -F 'image=@./clothing.jpg' \
  -F 'image=@./background.webp'

规则：

本地文件通过 multipart 的 image 字段上传。
多张图片按上传顺序传递。
URL 参考图必须是图片直链，不能是网页分享地址或 Markdown 链接。
images/edits 适合本地文件；纯文生图使用 images/generations。

7. 返回格式

成功响应从 data[].url 读取图片：

json

{
  "created": 1760000000,
  "data": [
    {
      "url": "https://cdn.example.com/generated-image.jpg"
    }
  ],
  "task_id": "img_abc123"
}

推荐显式传：

json

"response_format": "url"

客户端拿到 URL 后可展示、下载或转存到自己的对象存储。

8. SSE 实时状态

生成时间较长时可以传：

json

"stream": true

并添加：

http

Accept: text/event-stream

示例：

bash

curl -N 'https://api.zmoapi.cn/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  --data-raw '{
    "model": "banana2-4k",
    "prompt": "生成一张高质量城市夜景海报",
    "size": "16:9",
    "response_format": "url",
    "stream": true
  }'

事件可能包括：

text

event: progress
data: {"task_id":"img_abc123","status":"processing","progress":35}

event: result
data: {"task_id":"img_abc123","status":"completed","data":[{"url":"https://cdn.example.com/generated-image.jpg"}]}

event: done
data: {"task_id":"img_abc123","status":"completed"}

必须按 SSE 事件边界解析，不要把每一行独立当成完整 JSON。

9. 常见错误

HTTP	常见原因	处理方式
400	模型名、比例、分辨率、参考图字段错误	检查 `model`、`size`、`resolution` 与图片输入
401	API Key 缺失或无效	检查 Bearer Token
404	Base URL / 路径 / 模型错误	检查 `https://api.zmoapi.cn/v1` 与模型 ID
429	额度、并发或限流	降低并发并稍后重试
500/502/503	服务或上游暂时不可用	保存错误信息后再发起新任务

防止重复任务

生图 POST 网络超时并不能证明任务没有创建。不要对创建请求做无条件自动重试，否则可能重复生成并重复计费。

10. 与 Gemini 原生协议的区别

OpenAI 兼容协议	Gemini 原生协议
模型：`banana2-` / `nano-banana-2.1-` / `banana-pro-*`	模型：`gemini-3.1-flash-image-preview` / `gemini-nano-banana-2.1` / `gemini-3-pro-image-preview`
`/v1/images/generations`	`/v1beta/models/{model}:generateContent`
`/v1/images/edits`	`contents[].parts[]`
结果：`data[].url`	结果：`fileData.fileUri` 或 `inlineData.data`
适合 OpenAI SDK	适合 Gemini 原生客户端

Gemini · OpenAI 兼容协议 ​

快速信息 ​

1. 鉴权 ​

2. 模型 ID ​

Banana 2.1 ​

3. 文生图 ​

4. 常用请求字段 ​

5. URL 参考图（JSON） ​

images ​

image_urls ​

6. 本地文件参考图 / 图片编辑 ​

单图 ​

多图 ​

7. 返回格式 ​

8. SSE 实时状态 ​

9. 常见错误 ​

10. 与 Gemini 原生协议的区别 ​

Gemini · OpenAI 兼容协议

快速信息

1. 鉴权

2. 模型 ID

Banana 2.1

3. 文生图

4. 常用请求字段

5. URL 参考图（JSON）

`images`

`image_urls`

6. 本地文件参考图 / 图片编辑

单图

多图

7. 返回格式

8. SSE 实时状态

9. 常见错误

10. 与 Gemini 原生协议的区别