> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Nano Banana 2.1 API：1K–4K 图像生成与编辑

> 调用 gemini-nano-banana-2.1 生成和编辑 1K–4K 图片，每次 0.045 美元：14 种比例、最多 14 张参考图、三档思考级别，附 Gemini 原生与 OpenAI 兼容请求代码。

Nano Banana 2.1（`gemini-nano-banana-2.1`）是 Google 在 2026 年 10 月发布的 Nano Banana 2 更新版，文字渲染、信息图排版和多轮编辑的一致性更好。在老张API按次计费，每次 \$0.045，比 Nano Banana 2 便宜。

## 能力与参数

| 项目 | 内容 |
| - | - |
| 模型 ID | `gemini-nano-banana-2.1`（稳定版） |
| 官方名称 | Google Gemini Nano Banana 2.1 |
| 特点 | 文字与信息图排版更准，多轮编辑中人物和物体保持一致 |
| 价格 | 按次计费，2026 年 10 月 7 日公开价格配置为 \$0.045/次，最新价格见[模型与价格](/models) |
| 扣费 | 上游返回 HTTP 200 即扣一次，没有返回图片也扣费，见[计费规则](/api-capabilities/nano-banana-image#计费规则) |
| 令牌 | `default` 分组，计费模式为「按量优先」（推荐）或「按次计费」 |
| 调用方式 | Gemini 原生的 `generateContent` 可设置比例和分辨率；OpenAI 兼容的 `/v1/chat/completions` 输出 1K 图片 |
| 分辨率 `imageSize` | `1K`（默认）、`2K`、`4K`；不支持 `512` |
| 比例 `aspectRatio` | `1:1`、`1:4`、`4:1`、`1:8`、`8:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`，共 14 种 |
| 参考图 | 最多 14 张：高保真物体最多 10 张，人物一致性参考最多 4 张 |
| 思考模式 | 默认启用，级别 `minimal`、`medium`（默认）或 `high` |
| Google 搜索接地 | 支持网页搜索和图片搜索，每次检索另收 \$0.014 |

`imageSize` 是字符串，使用大写 K，例如 `2K`。不传 `aspectRatio` 时由模型按内容决定画幅。

常见输出尺寸：

* 1:1：1K 为 1024×1024，2K 为 2048×2048，4K 为 4096×4096。
* 16:9：1K 为 1376×768，2K 为 2752×1536。
* 其他比例的像素尺寸见 [Google 图像生成文档](https://ai.google.dev/gemini-api/docs/image-generation)。

五个 Nano Banana 模型的价格与能力对比见 [Nano Banana 总览](/api-capabilities/nano-banana-image)。

## 和 Nano Banana 2 怎么选

两者的请求结构和响应解析完全相同，切换时只改模型 ID。

| 对比项 | Nano Banana 2.1 | Nano Banana 2 |
| - | - | - |
| 模型 ID | `gemini-nano-banana-2.1` | `gemini-3.1-flash-image` |
| 老张API单价 | \$0.045/次 | \$0.055/次 |
| 分辨率 | `1K`、`2K`、`4K` | `512`、`1K`、`2K`、`4K` |
| 思考级别 | `minimal`、`medium`（默认）、`high` | `minimal`（默认）、`high` |
| 比例、参考图、搜索接地 | 相同 | 相同 |

* **新项目和 1K–4K 出图**：用 Nano Banana 2.1，单价更低，文字和排版更稳定。
* **需要 0.5K 预览图**：继续用 [Nano Banana 2](/api-capabilities/nano-banana2-image)，Nano Banana 2.1 传 `512` 会返回 400。
* Nano Banana 2 继续可用，价格不变，已有项目不需要迁移。

## 调用前准备

在[令牌管理](https://api.laozhang.ai/token)创建 API Key，计费模式选择「按量优先」（推荐）或「按次计费」：按量优先的令牌可以同时调用按量和按次计费的模型，按次计费的令牌只能调用按次计费的模型。

设置密钥并安装依赖：

```bash theme={null}
export LAOZHANG_API_KEY="替换为你的老张API密钥"
python -m pip install requests openai
```

本页示例还需要 [Nano Banana 总览](/api-capabilities/nano-banana-image#共用代码)中的 `nano_banana.py`，请把它保存到当前目录。cURL 示例也用它把响应文件保存为图片：

* `read_image()`：读取本地图片
* `save_images()`：从 Gemini 原生响应的 `parts[].inlineData` 或 OpenAI 兼容响应的 data URL 中取出 Base64 数据，解码后按 PNG、JPEG 或 WebP 保存

单次请求通常需要 15–40 秒，4K 更久。示例把超时设为 300 秒，你的客户端和代理也请留足时间。

## 生成图片

下面生成一张 16:9 的 2K 图片。需要 4K 时把 `imageSize` 改为 `4K`；比例从上表中任选。

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --fail-with-body --max-time 300 \
      "https://api.laozhang.ai/v1beta/models/gemini-nano-banana-2.1:generateContent" \
      -H "Authorization: Bearer $LAOZHANG_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "contents": [{
          "role": "user",
          "parts": [{"text": "生成一张图片：雨后傍晚的城市街角咖啡馆，暖色灯光映在湿润的路面上，招牌写着 BANANA CAFE"}]
        }],
        "generationConfig": {
          "responseModalities": ["IMAGE"],
          "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
        }
      }' \
      -o nb21-generate.json

    python nano_banana.py nb21-generate.json nb21-generate
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from nano_banana import post, save_images

    result = post("/v1beta/models/gemini-nano-banana-2.1:generateContent", {
        "contents": [{
            "role": "user",
            "parts": [{"text": "生成一张图片：雨后傍晚的城市街角咖啡馆，暖色灯光映在湿润的路面上，招牌写着 BANANA CAFE"}],
        }],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"},
        },
    })
    save_images(result, "nb21-generate")
    ```
  </Tab>
</Tabs>

成功后会得到 `nb21-generate-1.jpg` 等文件，扩展名随返回的图片格式变化。

## 编辑图片

把本地图片编码为 `inlineData`，和编辑指令放在同一条消息的 `parts` 中。多张参考图按顺序追加，提示词里用「第一张图」「第二张图」指代；最多 14 张。

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    IMAGE=nb21-generate-1.jpg   # 替换为你的图片路径

    # 生成 Base64 并用 jq 写入请求文件（需要 jq 1.6 及以上）
    base64 < "$IMAGE" | tr -d '\n' > image.b64

    jq -n --arg mime "$(file --mime-type -b "$IMAGE")" --rawfile data image.b64 '{
      contents: [{
        role: "user",
        parts: [
          {text: "把画面改成下雪的清晨，保留咖啡馆的结构、招牌文字和构图"},
          {inlineData: {mimeType: $mime, data: $data}}
        ]
      }],
      generationConfig: {
        responseModalities: ["IMAGE"],
        imageConfig: {aspectRatio: "16:9", imageSize: "2K"}
      }
    }' > nb21-edit-request.json

    curl --fail-with-body --max-time 300 \
      "https://api.laozhang.ai/v1beta/models/gemini-nano-banana-2.1:generateContent" \
      -H "Authorization: Bearer $LAOZHANG_API_KEY" \
      -H "Content-Type: application/json" \
      --data-binary @nb21-edit-request.json \
      -o nb21-edit.json

    python nano_banana.py nb21-edit.json nb21-edit
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import sys

    from nano_banana import post, read_image, save_images

    if not 3 <= len(sys.argv) <= 16:
        raise SystemExit('用法：python nb21_edit.py "编辑指令" 图片1 [图片2 ...]，最多 14 张')
    prompt, paths = sys.argv[1], sys.argv[2:]

    parts = [{"text": prompt}]
    for path in paths:
        mime, data = read_image(path)
        parts.append({"inlineData": {"mimeType": mime, "data": data}})

    result = post("/v1beta/models/gemini-nano-banana-2.1:generateContent", {
        "contents": [{"role": "user", "parts": parts}],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"},
        },
    })
    save_images(result, "nb21-edit")
    ```
  </Tab>
</Tabs>

Python 示例保存为 `nb21_edit.py` 后，单图编辑可以直接使用上一步生成的图片（文件名以实际保存的为准），多图合成时换成你自己的图片：

```bash theme={null}
python nb21_edit.py "把画面改成下雪的清晨，保留咖啡馆的结构、招牌文字和构图" nb21-generate-1.jpg
python nb21_edit.py "让第一张图中的人物穿上第二张图里的外套，站在第三张图的街道上" person.jpg jacket.png street.jpg
```

## 搜索接地

在请求中加入 `googleSearch` 工具，模型会先检索再出图，适合需要最新事实或真实地标外观的图片。下面同时启用网页搜索和图片搜索：

```python theme={null}
from nano_banana import post, save_images

result = post("/v1beta/models/gemini-nano-banana-2.1:generateContent", {
    "contents": [{
        "role": "user",
        "parts": [{"text": "生成一张水彩插画：当前世界最高的建筑，在画面下方写上它的名字"}],
    }],
    "tools": [{"googleSearch": {"searchTypes": {"webSearch": {}, "imageSearch": {}}}}],
    "generationConfig": {
        "responseModalities": ["TEXT", "IMAGE"],
        "imageConfig": {"aspectRatio": "2:3"},
    },
})
save_images(result, "nb21-grounded")
metadata = result["candidates"][0].get("groundingMetadata", {})
print("网页搜索：", metadata.get("webSearchQueries"))
print("图片搜索：", metadata.get("imageSearchQueries"))
```

* `searchTypes` 必须写成对象。不设置时只启用网页搜索，只写 `imageSearch` 时只用图片搜索。
* 每次是否检索、用哪种搜索由模型决定，实际用到的检索词在 `groundingMetadata` 中。
* 目前不能把搜索到的真实人物图片用作参考；向最终用户展示接地结果时，需要按 [Google 搜索接地说明](https://ai.google.dev/gemini-api/docs/google-search)展示搜索建议。
* 开启搜索接地的请求，在 \$0.045 之外每次检索另收 \$0.014。检索 2 次就是 \$0.073，调用日志会写明检索次数，见 [Nano Banana 总览的计费规则](/api-capabilities/nano-banana-image#计费规则)。

## OpenAI 兼容格式

已有 OpenAI SDK 代码时，把 `base_url` 设为 `https://api.laozhang.ai/v1`，`model` 改为 `gemini-nano-banana-2.1` 即可。

这种格式不能设置比例和分辨率，输出 1K 图片，画幅由模型按内容决定，常见为 16:9 横图。需要固定比例或 2K、4K 时，用上面的 Gemini 原生格式。示例关闭了 SDK 的自动重试，避免超时后重复生成和扣费。

### 生成图片

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --fail-with-body --max-time 300 \
      "https://api.laozhang.ai/v1/chat/completions" \
      -H "Authorization: Bearer $LAOZHANG_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "gemini-nano-banana-2.1",
        "stream": false,
        "messages": [
          {"role": "user", "content": "生成一张图片：木桌上的一杯拿铁，拉花是一只小猫，俯拍"}
        ]
      }' \
      -o nb21-openai.json

    python nano_banana.py nb21-openai.json nb21-openai
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os

    from openai import OpenAI

    from nano_banana import save_images

    client = OpenAI(
        api_key=os.environ["LAOZHANG_API_KEY"],
        base_url="https://api.laozhang.ai/v1",
        timeout=300,
        max_retries=0,
    )
    response = client.chat.completions.create(
        model="gemini-nano-banana-2.1",
        messages=[{"role": "user", "content": "生成一张图片：木桌上的一杯拿铁，拉花是一只小猫，俯拍"}],
    )
    save_images(response.model_dump(), "nb21-openai")
    ```
  </Tab>
</Tabs>

### 编辑图片

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --fail-with-body --max-time 300 \
      "https://api.laozhang.ai/v1/chat/completions" \
      -H "Authorization: Bearer $LAOZHANG_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "gemini-nano-banana-2.1",
        "stream": false,
        "messages": [{
          "role": "user",
          "content": [
            {"type": "text", "text": "把这张图变成梵高《星月夜》风格的油画"},
            {"type": "image_url", "image_url": {"url": "https://example.com/your-image.jpg"}}
          ]
        }]
      }' \
      -o nb21-openai-edit.json

    python nano_banana.py nb21-openai-edit.json nb21-openai-edit
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    import sys

    from openai import OpenAI

    from nano_banana import read_image, save_images

    if len(sys.argv) < 3:
        raise SystemExit('用法：python nb21_openai_edit.py "编辑指令" 图片1 [图片2 ...]')
    prompt, paths = sys.argv[1], sys.argv[2:]

    content = [{"type": "text", "text": prompt}]
    for path in paths:
        mime, data = read_image(path)
        content.append({"type": "image_url", "image_url": {"url": f"data:{mime};base64,{data}"}})

    client = OpenAI(
        api_key=os.environ["LAOZHANG_API_KEY"],
        base_url="https://api.laozhang.ai/v1",
        timeout=300,
        max_retries=0,
    )
    response = client.chat.completions.create(
        model="gemini-nano-banana-2.1",
        messages=[{"role": "user", "content": content}],
    )
    save_images(response.model_dump(), "nb21-openai-edit")
    ```
  </Tab>
</Tabs>

cURL 示例中的 `https://example.com/your-image.jpg` 需要替换为你的图片 URL，图片要能被公网直接访问；本地图片请使用 Python 示例，它会把图片转成 data URL。

## 错误与计费

参数不合法时返回 HTTP 400，不扣费：

| 请求内容 | 结果 |
| - | - |
| `imageSize` 为 `512` | 400，错误信息为 `Image size 512 is not supported for this model` |
| `aspectRatio` 不在 14 种之内，例如 `7:3` | 400，错误信息可能为空，请对照上表检查比例 |

计费要点：

* 每次调用 \$0.045，不随分辨率、思考级别、参考图数量或生成 / 编辑而变化。
* 开启搜索接地时，每次检索另收 \$0.014。
* 上游返回 HTTP 200 即扣费，没有返回图片也一样；原因与避免方法见[避免没有图片的扣费](/api-capabilities/nano-banana-image#避免没有图片的扣费)。
* 客户端超时不等于请求失败，重试前先在[调用日志](/faq/call-logs)确认请求状态。

## 常见问题

### 从 Nano Banana 2 切换要改什么？

把模型 ID 从 `gemini-3.1-flash-image` 改为 `gemini-nano-banana-2.1`，请求结构和响应解析不变。

切换前检查两处：

* 请求里用了 `"imageSize": "512"` 的，改成 `1K` 或继续用 Nano Banana 2。
* 没有设置 `thinkingLevel` 时，Nano Banana 2.1 默认按 `medium` 思考，Nano Banana 2 默认是 `minimal`。想要更快出图，显式设为 `minimal`。

### 思考级别怎么调？会影响价格吗？

使用 Gemini 原生格式时，在 `generationConfig.thinkingConfig.thinkingLevel` 中设置级别，可选 `minimal`、`medium`、`high`：

```json theme={null}
"thinkingConfig": {"thinkingLevel": "high"}
```

级别越高，构图和文字推敲越充分，耗时也越长。老张API只按次计费，三档都是 \$0.045/次（Google 官方则会按思考 tokens 另外计费）。

另外设置 `"includeThoughts": true` 时，响应会多出带 `"thought": true` 的思考文字和中间草图，保存时只取最后一张不带 `thought` 的图片。

### 4K 和 1K 价格一样吗？

一样，都是 \$0.045/次。Google 官方按输出 tokens 计费，4K 每张约 \$0.113、1K 约 \$0.0336，见 [Google 官方价格](https://ai.google.dev/gemini-api/docs/pricing)。只出 1K 小图时，[Nano Banana 2 Lite](/api-capabilities/nano-banana-2-lite-api) 的单价更低。

### OpenAI 兼容格式为什么返回横图？

OpenAI 兼容格式不能传比例，画幅由模型按提示词决定，常见为 16:9。需要方图或竖图时，改用 Gemini 原生格式并设置 `aspectRatio`。

## 相关文档

* [Nano Banana 总览](/api-capabilities/nano-banana-image)：五个模型对比、两种调用方式、计费规则与共用代码
* [Nano Banana 2 API](/api-capabilities/nano-banana2-image)：需要 0.5K 输出时使用
* [Nano Banana 2 Lite API](/api-capabilities/nano-banana-2-lite-api)：只需 1K 时的轻量模型
* [Nano Banana Pro API](/api-capabilities/nano-banana-pro-image)：复杂构图与专业成片
* [Gemini 协议](/api-reference/gemini)：原生请求结构与 SDK 配置
* [Google Nano Banana 2.1 模型说明](https://ai.google.dev/gemini-api/docs/models/gemini-nano-banana-2.1)：官方能力与限制
* [Google 图像生成文档](https://ai.google.dev/gemini-api/docs/image-generation)：比例、像素尺寸与参考图上限


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.