Nano Banana 原生

与 Gemini 共用 generateContent 协议
模型 ID 换成 nano-banana 系列
图片以 inlineData Base64 返回

POSTv1beta/models/{model}:generateContent

认证

string必填

Gemini 原生格式认两种写法：请求头 x-goog-api-key: YOUR_API_KEY，或查询参数 ?key=YOUR_API_KEY。两者同时存在时以请求头为准。Key 与控制台创建的 API Key 相同。

为什么和 Gemini 是同一个接口

Nano Banana 是 Gemini 系列的图像模型，上游协议完全一致，区别只在 {model} 位置填的模型 ID。通用结构见Gemini 原生，本节只讲 Nano Banana 特有的部分。

请求结构

contents (array / 必填) — 对话内容，每条含 role 与 parts。
contents[].parts (array / 必填) — 文本用 {"text": "..."}，参考图用 {"inlineData": {...}}。
generationConfig.responseModalities (array / 必填) — 必须同时包含 TEXT 与 IMAGE。
generationConfig.imageConfig (object / 可选) — 画幅与分辨率档位。

支持的场景

场景	写法
文生图	`parts` 里只有一段 `text`
单图编辑	`parts` 里加一段 `inlineData`，再跟 `text` 描述改动
多图参考	`parts` 里加多段 `inlineData`，最多 20 张
指定画幅	`imageConfig.aspectRatio`

Scenario	How
Text to image	`parts` holds one `text` entry
Single-image edit	Add an `inlineData` part, then a `text` part describing the change
Multi-image reference	Add several `inlineData` parts, up to 20
Aspect ratio	`imageConfig.aspectRatio`

请求参数

string必填

路径参数。填 nano-banana 系列的模型 ID，必须写全名。

array必填

对话内容。

array必填

固定 ["TEXT", "IMAGE"]。

string可选

画幅比例，如 1:1、4:3、16:9、9:16。

string可选

输出档位，1K、2K、4K。

array可选

安全阈值设置。

与官方版、扩展版的差别

版本	计费	参考图上限
官方版	按 token 计费	20MB
扩展版	按张计费	合计 50MB

原生接口的请求结构完全相同，差异由 model 决定，不要混用两版的字段。

Version	Billing	Reference limit
Official	Billed by token	20MB
Extended	Billed per image	50MB total

The native request shape is identical; the model decides the difference, so don't mix fields from the two versions.

响应

图片以 inlineData 返回，data 是纯 Base64：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          { "inlineData": { "mimeType": "image/png", "data": "iVBORw0KGgoAAAANSUhEUg..." } }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 22,
    "candidatesTokenCount": 1290,
    "totalTokenCount": 1312
  }
}

candidates[].content.parts[].inlineData.data (string) — 纯 Base64，自行拼 data:<mimeType>;base64, 才能用。
candidates[].finishReason (string) — 被安全策略拦截时为 SAFETY。
usageMetadata (object) — token 用量，官方版按此计费。

返回值没有可访问的图片地址，只有 Base64。需要 URL 时先自行转存。

Images come back as inlineData, with raw Base64 in data:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          { "inlineData": { "mimeType": "image/png", "data": "iVBORw0KGgoAAAANSUhEUg..." } }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 22,
    "candidatesTokenCount": 1290,
    "totalTokenCount": 1312
  }
}

candidates[].content.parts[].inlineData.data (string) — raw Base64; prepend data:<mimeType>;base64, to use it.
candidates[].finishReason (string) — SAFETY when blocked.
usageMetadata (object) — token usage, which is how the official version bills.

There's no fetchable URL, only Base64. Store it yourself if you need one.

错误码

HTTP	含义
400	`responseModalities` 缺 `IMAGE`，或模型 ID 写错
401	Key 缺失或无效
429	触发限流

常见 400 原因：model 用了缩写；参考图超过上限；inlineData.data 带了 data: 前缀。

HTTP	Meaning
400	`responseModalities` missing `IMAGE`, or a wrong model ID
401	Key missing or invalid
429	Rate limit hit

Common 400 causes: an abbreviated model; references over the limit; a data: prefix inside inlineData.data.

使用示例

parts 里只放文本是文生图；先放 inlineData 再放文本是编辑。imageConfig 控制画幅与档位。