Gemini 原生协议

知梦 Gemini 生图支持 Gemini generateContent 原生调用。本文只描述知梦当前线上实际可用的协议与模型 ID。

Base URL：https://api.zmoapi.cn

1. 鉴权与接口

所有请求使用知梦 API Key：

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json; charset=utf-8

普通请求：

http

POST /v1beta/models/{model}:generateContent

SSE 流式请求：

http

POST /v1beta/models/{model}:streamGenerateContent?alt=sse

获取当前密钥可用模型：

http

GET /v1beta/models

bash

curl 'https://api.zmoapi.cn/v1beta/models' \
  -H 'Authorization: Bearer YOUR_API_KEY'

2. 知梦当前原生模型 ID

产品	Gemini 原生模型 ID	支持分辨率	价格
Banana 2	`gemini-3.1-flash-image-preview`	1K / 2K / 4K	¥0.08 / 张
Banana 2.1	`gemini-nano-banana-2.1`	1K / 2K / 4K	¥0.06 / 张
Banana Pro	`gemini-3-pro-image-preview`	1K / 2K / 4K	¥0.09 / 张

接入知梦时请使用上表 ID

Banana 2 与 Banana Pro 在知梦的原生模型 ID 仍为 gemini-3.1-flash-image-preview 与 gemini-3-pro-image-preview；Banana 2.1 使用 gemini-nano-banana-2.1。请以知梦 /v1beta/models 返回结果为准，不要自行修改模型名。

banana2-*、nano-banana-2.1-* 与 banana-pro-* 属于 OpenAI 兼容协议模型名，不要拿来调用 generateContent。

如果模型列表返回：

text

models/gemini-3.1-flash-image-preview

实际调用时去掉 models/：

text

gemini-3.1-flash-image-preview

Banana 2.1

Banana 2.1 沿用本页的 contents[].parts[]、URL 参考图 fileData、Base64 参考图 inlineData、多图混合、URI / INLINE 返回和 SSE 流式调用方式。所有分辨率使用同一个原生模型 ID gemini-nano-banana-2.1，通过 generationConfig.imageConfig.imageSize 选择 1K、2K 或 4K，均为 ¥0.06 / 张。

以下为 2K 文生图示例：

bash

curl 'https://api.zmoapi.cn/v1beta/models/gemini-nano-banana-2.1:generateContent' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json; charset=utf-8' \
  --data-raw '{
    "contents": [{
      "role": "user",
      "parts": [{ "text": "生成一张16:9的现代科技产品宣传图，干净明亮，产品位于画面中心" }]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" },
      "responseFormat": { "image": { "delivery": "URI" } }
    }
  }'

流式生成时使用同一个模型 ID，将接口后缀改为 :streamGenerateContent?alt=sse，请求体不变。单图 URL、Base64 和多参考图示例见本页后续章节。

在线调试 Banana 2.1 · Gemini 原生协议 →

3. 请求结构

完整请求主要由两部分组成：

contents：提示词与参考图片。
generationConfig：返回模态、比例、分辨率和图片交付方式。

基础结构：

json

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "在这里填写提示词" }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "2K"
    },
    "responseFormat": {
      "image": {
        "delivery": "URI"
      }
    }
  }
}

4. 分辨率

使用：

json

"generationConfig": {
  "imageConfig": {
    "imageSize": "2K"
  }
}

允许值：

参数	含义
`1K`	常规分辨率
`2K`	高清分辨率
`4K`	超高清分辨率

注意：

K 必须大写。
正确："imageSize":"2K"。
错误："imageSize":"2k"。
不要用 2048x2048 代替 2K。
实际像素宽高由模型和画幅共同决定。

5. 宽高比

使用：

json

"imageConfig": {
  "aspectRatio": "16:9",
  "imageSize": "2K"
}

常用比例：

text

1:1
16:9
9:16
4:3
3:4
3:2
2:3
5:4
4:5
21:9

Flash 图片模型还支持：

text

1:4
4:1
1:8
8:1

自动比例

希望模型自行判断时，直接省略 aspectRatio：

json

"imageConfig": {
  "imageSize": "2K"
}

不要发送：

json

"aspectRatio": "auto"

6. 纯文生图

以下使用 Banana 2 对应的原生 Preview ID：

bash

curl 'https://api.zmoapi.cn/v1beta/models/gemini-3.1-flash-image-preview:generateContent' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json; charset=utf-8' \
  --data-raw '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "生成一张16:9的现代科技产品宣传图，干净明亮，产品位于画面中心"
          }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "2K"
      },
      "responseFormat": {
        "image": {
          "delivery": "URI"
        }
      }
    }
  }'

使用 Banana Pro 时将模型改为：

text

gemini-3-pro-image-preview

7. 单张 URL 参考图

公网图片使用 fileData.fileUri：

json

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "保持人物、服装和场景一致，将画面改成16:9电影场景"
        },
        {
          "fileData": {
            "mimeType": "image/png",
            "fileUri": "https://example.com/reference.png"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "2K"
    },
    "responseFormat": {
      "image": { "delivery": "URI" }
    }
  }
}

URL 必须：

是公网可访问的 HTTP / HTTPS 直链；
直接返回图片文件；
不依赖登录 Cookie；
不能是网页分享页；
fileUri 中不要放 Markdown 链接格式。

8. 单张 Base64 参考图

本地图片使用 inlineData：

json

{
  "inlineData": {
    "mimeType": "image/jpeg",
    "data": "BASE64_IMAGE_DATA"
  }
}

inlineData.data 只能包含纯 Base64。

正确：

text

iVBORw0KGgoAAAANSUhEUgAA...

错误：

text

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...

常见 MIME：

text

image/png
image/jpeg
image/webp

9. 多张 URL 参考图

每张参考图对应一个独立的 fileData Part：

json

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "第一张是商品主体，第二张是目标场景，第三张是配色参考。"
        },
        {
          "fileData": {
            "mimeType": "image/png",
            "fileUri": "https://example.com/product.png"
          }
        },
        {
          "fileData": {
            "mimeType": "image/jpeg",
            "fileUri": "https://example.com/scene.jpg"
          }
        },
        {
          "fileData": {
            "mimeType": "image/webp",
            "fileUri": "https://example.com/color.webp"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "4K"
    },
    "responseFormat": {
      "image": { "delivery": "URI" }
    }
  }
}

图片在 parts 中的顺序就是参考图顺序。建议提示词明确每张图片的用途。

10. URL 与 Base64 混合

两种图片输入可以混合：

json

{
  "parts": [
    {
      "text": "第一张为人物，第二张为本地服装参考，第三张为背景。"
    },
    {
      "fileData": {
        "mimeType": "image/png",
        "fileUri": "https://example.com/person.png"
      }
    },
    {
      "inlineData": {
        "mimeType": "image/jpeg",
        "data": "CLOTHING_IMAGE_BASE64"
      }
    },
    {
      "fileData": {
        "mimeType": "image/webp",
        "fileUri": "https://example.com/scene.webp"
      }
    }
  ]
}

一个 Part 只能包含一种数据类型。

11. 返回 URL（推荐）

请求中指定：

json

"responseFormat": {
  "image": {
    "delivery": "URI"
  }
}

图片结果读取：

text

candidates[].content.parts[].fileData.fileUri

示意：

json

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "fileData": {
              "mimeType": "image/jpeg",
              "fileUri": "https://cdn.example.com/generated-image.jpg"
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ]
}

12. 返回 Base64

需要 Base64 时：

json

"responseFormat": {
  "image": {
    "delivery": "INLINE"
  }
}

结果读取：

text

candidates[].content.parts[].inlineData.data

一般业务推荐 URI，可以减少响应体积和内存占用。

13. JavaScript 完整示例

async function generateGeminiImage({
  apiKey,
  model = "gemini-3.1-flash-image-preview",
  prompt,
  references = [],
  aspectRatio = "16:9",
  imageSize = "2K",
  delivery = "URI"
}) {
  const parts = [{ text: prompt }];

  for (const reference of references) {
    if (typeof reference === "string") {
      parts.push({
        fileData: {
          mimeType: "image/png",
          fileUri: reference
        }
      });
    } else {
      parts.push(reference);
    }
  }

  const imageConfig = { imageSize };
  if (aspectRatio) imageConfig.aspectRatio = aspectRatio;

  const response = await fetch(
    `https://api.zmoapi.cn/v1beta/models/${encodeURIComponent(model)}:generateContent`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json; charset=utf-8"
      },
      body: JSON.stringify({
        contents: [{ role: "user", parts }],
        generationConfig: {
          responseModalities: ["TEXT", "IMAGE"],
          imageConfig,
          responseFormat: { image: { delivery } }
        }
      })
    }
  );

  const payload = await response.json();
  if (!response.ok) {
    throw new Error(payload.error?.message || `HTTP ${response.status}`);
  }

  const images = [];
  const texts = [];

  for (const candidate of payload.candidates || []) {
    for (const part of candidate.content?.parts || []) {
      if (part.thought === true) continue;
      if (typeof part.text === "string") texts.push(part.text);
      if (part.fileData?.fileUri) {
        images.push({ type: "url", url: part.fileData.fileUri });
      }
      if (part.inlineData?.data) {
        images.push({
          type: "base64",
          mimeType: part.inlineData.mimeType,
          data: part.inlineData.data
        });
      }
    }
  }

  return { images, texts, raw: payload };
}

14. SSE 流式调用

接口：

text

POST https://api.zmoapi.cn/v1beta/models/{model}:streamGenerateContent?alt=sse

请求体与普通 generateContent 相同，并增加：

http

Accept: text/event-stream

示例：

bash

curl -N 'https://api.zmoapi.cn/v1beta/models/gemini-3.1-flash-image-preview:streamGenerateContent?alt=sse' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'Accept: text/event-stream' \
  --data-raw '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text":"生成一张16:9的现代产品宣传图"}]
      }
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "2K"
      },
      "responseFormat": {
        "image": {"delivery":"URI"}
      }
    }
  }'

服务会返回多个 SSE 事件。客户端应按事件边界解析，不要假定每一行都是完整 JSON。

15. 错误响应

json

{
  "error": {
    "code": 400,
    "message": "具体错误信息",
    "status": "INVALID_ARGUMENT"
  }
}

常见状态：

HTTP	状态	常见原因
`400`	`INVALID_ARGUMENT`	JSON、字段、比例、分辨率或 Base64 错误
`401`	`UNAUTHENTICATED`	API Key 缺失或无效
`403`	`PERMISSION_DENIED`	当前密钥无模型权限
`404`	`NOT_FOUND`	模型名或接口路径错误
`429`	`RESOURCE_EXHAUSTED`	额度、并发或请求频率不足
`500`	`INTERNAL`	服务内部错误
`503`	`UNAVAILABLE`	暂无可用渠道或上游临时不可用

调用失败时优先展示 error.message。

16. 重要规则

知梦当前原生模型使用 gemini-3.1-flash-image-preview / gemini-nano-banana-2.1 / gemini-3-pro-image-preview。
参考图必须放在 contents[].parts[] 中。
URL 图片使用 fileData.fileUri。
本地图片使用 inlineData.data，内容必须是纯 Base64。
多图顺序以 parts 中的顺序为准。
每个 Part 只能包含一种数据类型。
自动比例必须省略 aspectRatio，不要传 auto。
imageSize 中的 K 必须大写。
最终图片读取非 thought Part 中的 fileData 或 inlineData。
不要因为超时或断连自动重复提交生图请求，以免产生额外任务。

Gemini 原生协议 ​

1. 鉴权与接口 ​

2. 知梦当前原生模型 ID ​

Banana 2.1 ​

3. 请求结构 ​

4. 分辨率 ​

5. 宽高比 ​

自动比例 ​

6. 纯文生图 ​

7. 单张 URL 参考图 ​

8. 单张 Base64 参考图 ​

9. 多张 URL 参考图 ​

10. URL 与 Base64 混合 ​

11. 返回 URL（推荐） ​

12. 返回 Base64 ​

13. JavaScript 完整示例 ​

14. SSE 流式调用 ​

15. 错误响应 ​

16. 重要规则 ​

17. 相关页面 ​

Gemini 原生协议

1. 鉴权与接口

2. 知梦当前原生模型 ID

Banana 2.1

3. 请求结构

4. 分辨率

5. 宽高比

自动比例

6. 纯文生图

7. 单张 URL 参考图

8. 单张 Base64 参考图

9. 多张 URL 参考图

10. URL 与 Base64 混合

11. 返回 URL（推荐）

12. 返回 Base64

13. JavaScript 完整示例

14. SSE 流式调用

15. 错误响应

16. 重要规则

17. 相关页面