> ## 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 Pro API：1K–4K 图像生成

> 调用 gemini-3-pro-image 生成 1K–4K 图片：10 种比例、Google 搜索接地，附两种请求格式的示例与结果保存。

Nano Banana Pro（`gemini-3-pro-image`）适合复杂指令、精确文字渲染和专业素材，在老张API可以生成 1K–4K 图片并开启 Google 搜索接地，按次计费。

## 能力与参数

| 项目 | 内容 |
| - | - |
| 模型 ID | `gemini-3-pro-image`（稳定版） |
| 官方名称 | Google Gemini 3 Pro Image |
| 价格 | 按次计费，2026 年 9 月 24 日公开价格配置为 \$0.09/次，最新价格见[模型与价格](/models) |
| 扣费 | 上游返回 HTTP 200 即扣一次，没有返回图片也扣费，见[计费规则](/api-capabilities/nano-banana-image#计费规则) |
| 调用方式 | Gemini 原生的 `generateContent` 可设置比例和分辨率；OpenAI 兼容的 `/v1/chat/completions` 输出 1K 图片 |
| 图片编辑 | 修改已有图片或合成多张参考图，见 [Nano Banana Pro 图片编辑 API](/api-capabilities/nano-banana-pro-image-edit) |
| 分辨率 `imageSize` | `1K`、`2K`、`4K`；不传时为 `1K` |
| 比例 `aspectRatio` | `1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`，共 10 种 |
| 参考图 | 最多 14 张：高保真物体最多 6 张，人物一致性参考最多 5 张，风格参考最多 3 张 |
| 思考模式 | 默认启用，API 中不能关闭 |
| Google 搜索接地 | 支持 |

[Nano Banana 2](/api-capabilities/nano-banana2-image) 同样默认启用思考模式、支持搜索接地，还多支持 0.5K 分辨率和 4 种超宽、超高比例。能力依据 [Google 图像生成文档](https://ai.google.dev/gemini-api/docs/image-generation)，五个模型的对比见 [Nano Banana 总览](/api-capabilities/nano-banana-image)。

Google 已于 2026 年 6 月 25 日停止 `gemini-3-pro-image-preview`（见 [Google 弃用页](https://ai.google.dev/gemini-api/docs/deprecations)）。在老张API，`-preview` ID 会映射到对应的正式 ID，请直接使用正式 ID `gemini-3-pro-image`。

Google 文档列出的输出像素尺寸如下，`imageSize` 必须使用大写 K：

| 比例 | 1K | 2K | 4K |
| - | - | - | - |
| 1:1 | 1024×1024 | 2048×2048 | 4096×4096 |
| 2:3 | 848×1264 | 1696×2528 | 3392×5056 |
| 3:2 | 1264×848 | 2528×1696 | 5056×3392 |
| 3:4 | 896×1200 | 1792×2400 | 3584×4800 |
| 4:3 | 1200×896 | 2400×1792 | 4800×3584 |
| 4:5 | 928×1152 | 1856×2304 | 3712×4608 |
| 5:4 | 1152×928 | 2304×1856 | 4608×3712 |
| 9:16 | 768×1376 | 1536×2752 | 3072×5504 |
| 16:9 | 1376×768 | 2752×1536 | 5504×3072 |
| 21:9 | 1584×672 | 3168×1344 | 6336×2688 |

## 价格与能力一览

| 分辨率 | 生成 | 编辑 |
| - | - | - |
| 1K | \$0.09/次 | \$0.09/次 |
| 2K | \$0.09/次 | \$0.09/次 |
| 4K | \$0.09/次 | \$0.09/次 |

价格为 2026 年 9 月 24 日公开价格配置，核对日期 2026 年 10 月 10 日；分辨率和参考图数量不改变单价，Google 搜索接地按检索次数另收 \$0.014。模型来自 Google 官方渠道，按次线路以固定单价计费，低于 Google 按 token 计费的 1K–4K 单张价格。

| 能力 | 支持情况 |
| - | - |
| 需要 Google 账号 | 不需要，只用老张API密钥 |
| 文生图与图生图编辑 | 都支持，同价；编辑见 [Nano Banana Pro 图片编辑 API](/api-capabilities/nano-banana-pro-image-edit) |
| 参考图 | 最多 14 张 |
| 一次出图 | 每次请求一张；多张分多次请求 |
| 分辨率与比例 | 1K、2K、4K；10 种比例（Gemini 原生格式） |
| 协议 | Gemini 原生 `generateContent`，或 OpenAI 兼容 `/v1/chat/completions` |
| 并发 | 平台不限制，`429` 来自上游容量，见[并发与 429](/faq/api-concurrency) |
| 失败扣费 | HTTP 200 无图扣一次；429、5xx 未进入生成不扣费，见[扣费与失败规则](/api-capabilities/image-billing-and-failures) |

## 调用前准备

在[令牌管理](https://api.laozhang.ai/token)创建 API Key，计费模式选择「按量优先」（推荐）或「按次计费」：按量优先的令牌可以同时调用按量和按次计费的模型，按次计费的令牌只能调用按次计费的模型。无图响应与重试的计费说明见[计费规则](/api-capabilities/nano-banana-image#计费规则)。

设置密钥并安装依赖：

```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 保存

示例使用 `Authorization: Bearer` 请求头。Gemini 原生格式也接受 `x-goog-api-key` 请求头；不要把密钥写进 URL 查询参数（例如 `?key=`）。

## 生成图片

下面生成一张 16:9 的 4K 图片。4K 请求耗时更长，示例把超时设为 300 秒。

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --fail-with-body --max-time 300 \
      "https://api.laozhang.ai/v1beta/models/gemini-3-pro-image:generateContent" \
      -H "Authorization: Bearer $LAOZHANG_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "contents": [{
          "role": "user",
          "parts": [{"text": "生成一张图片：黄昏时分的未来城市天际线，玻璃幕墙反射晚霞，街道上方有悬浮列车，电影感构图"}]
        }],
        "generationConfig": {
          "responseModalities": ["IMAGE"],
          "imageConfig": {"aspectRatio": "16:9", "imageSize": "4K"}
        }
      }' \
      -o pro-generate.json

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

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

    result = post("/v1beta/models/gemini-3-pro-image:generateContent", {
        "contents": [{
            "role": "user",
            "parts": [{"text": "生成一张图片：黄昏时分的未来城市天际线，玻璃幕墙反射晚霞，街道上方有悬浮列车，电影感构图"}],
        }],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {"aspectRatio": "16:9", "imageSize": "4K"},
        },
    })
    save_images(result, "pro-generate")
    ```
  </Tab>
</Tabs>

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

## 编辑图片

把本地图片编码为 `inlineData`，和编辑指令放在同一条消息的 `parts` 中，`mimeType` 必须与图片的实际格式一致。下面把上一步生成的图片改成雨夜风格（文件名以实际保存的为准）：

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

mime, data = read_image("pro-generate-1.png")  # 替换为你的图片路径

result = post("/v1beta/models/gemini-3-pro-image:generateContent", {
    "contents": [{
        "role": "user",
        "parts": [
            {"text": "把画面改成赛博朋克风格的雨夜，霓虹灯更强烈，保留建筑轮廓和构图"},
            {"inlineData": {"mimeType": mime, "data": data}},
        ],
    }],
    "generationConfig": {
        "responseModalities": ["IMAGE"],
        "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"},
    },
})
save_images(result, "pro-edit")
```

成功后会得到 `pro-edit-1.png` 等文件。多图合成（最多 14 张参考图）、公网图片 URL 输入、OpenAI 兼容格式的编辑写法和常见错误，见 [Nano Banana Pro 图片编辑 API](/api-capabilities/nano-banana-pro-image-edit)。

## 用 OpenAI 兼容格式生成

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

这种格式不能设置比例和分辨率，文生图输出 1:1 的 1K 图片。示例关闭了 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-3-pro-image",
        "stream": false,
        "messages": [
          {"role": "user", "content": "生成一张图片：极简风格的咖啡馆菜单海报，标题为「今日特调」，列出三款饮品和价格"}
        ]
      }' \
      -o pro-openai.json

    python nano_banana.py pro-openai.json pro-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-3-pro-image",
        messages=[{
            "role": "user",
            "content": "生成一张图片：极简风格的咖啡馆菜单海报，标题为「今日特调」，列出三款饮品和价格",
        }],
    )
    save_images(response.model_dump(), "pro-openai")
    ```
  </Tab>
</Tabs>

用 OpenAI 兼容格式编辑图片时，把图片放进 `content` 数组的 `image_url`，写法见 [Nano Banana Pro 图片编辑 API](/api-capabilities/nano-banana-pro-image-edit#openai-兼容格式)。

## 搜索接地

开启 Google 搜索接地后，模型会先搜索实时信息再生成图片，适合天气图表、近期事件信息图等依赖最新数据的任务。在请求中加入 `googleSearch` 工具；示例同时请求文字和图片，以便读取模型对搜索结果的说明。

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --fail-with-body --max-time 300 \
      "https://api.laozhang.ai/v1beta/models/gemini-3-pro-image:generateContent" \
      -H "Authorization: Bearer $LAOZHANG_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "contents": [{
          "role": "user",
          "parts": [{"text": "搜索旧金山未来 5 天的天气预报，做成一张简洁现代的天气图表"}]
        }],
        "tools": [{"googleSearch": {}}],
        "generationConfig": {
          "responseModalities": ["TEXT", "IMAGE"],
          "imageConfig": {"aspectRatio": "16:9"}
        }
      }' \
      -o pro-grounded.json

    python nano_banana.py pro-grounded.json pro-grounded
    ```
  </Tab>

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

    result = post("/v1beta/models/gemini-3-pro-image:generateContent", {
        "contents": [{
            "role": "user",
            "parts": [{"text": "搜索旧金山未来 5 天的天气预报，做成一张简洁现代的天气图表"}],
        }],
        "tools": [{"googleSearch": {}}],
        "generationConfig": {
            "responseModalities": ["TEXT", "IMAGE"],
            "imageConfig": {"aspectRatio": "16:9"},
        },
    })
    save_images(result, "pro-grounded")
    for part in result["candidates"][0]["content"]["parts"]:
        if "text" in part and not part.get("thought"):
            print(part["text"])
    ```
  </Tab>
</Tabs>

图片和文字都在 `candidates[0].content.parts` 中；搜索来源位于 `candidates[0].groundingMetadata`。

* 同样的请求把模型换成 `gemini-3.1-flash-image` 即可用于 Nano Banana 2；Nano Banana 2 Lite 不支持搜索接地。
* 向最终用户展示接地结果时，需要按 Google 条款展示搜索建议。
* 搜索接地按检索次数另外计费，每次 \$0.014；检索次数由模型决定，以调用日志为准，见 [Nano Banana 总览的计费规则](/api-capabilities/nano-banana-image#计费规则)。

## 常见问题

### 要不要从 Pro 换成 Nano Banana 2？

多数任务可以先试 Nano Banana 2（`gemini-3.1-flash-image`）：请求结构相同，切换只改模型 ID，单价更低。

依赖世界知识、多语言文字和精确品牌细节的成片，或编辑时需要风格参考图、最多 5 张人物参考图时，继续用 Pro。切换前用自己的提示词和图片在两个模型上各试几次，逐项差异见 [从 Nano Banana Pro 切换](/api-capabilities/nano-banana2-image#从-nano-banana-pro-切换)。

### 思考模式能关闭吗？会影响价格吗？

不能关闭。Google 说明 Gemini 3 图像模型默认启用思考，API 中无法关闭；`thinkingLevel` 只能调整 Nano Banana 2 和 2 Lite 的思考级别，传给 Pro 不会生效。

思考时模型会生成临时图片检验构图，这些图片可能和最终结果一起返回，最后一张是最终结果，处理方法见[一次请求能生成多张图吗](/api-capabilities/nano-banana-image#常见问题)。

Pro 按次计费，思考多少都不改变单价。

### 图片里的文字写错或变形怎么办？

Google 建议先让模型生成要放进图片的文字，确认无误后，再要求它生成包含这段文字的图片。提示词里把要出现的文字原样放进引号，并说明位置和字体风格，写法示例见[编辑指令怎么写](/api-capabilities/nano-banana-pro-image-edit#编辑指令怎么写)。仍有错字时，把结果图作为输入，只要求修改那一处文字。

## 相关文档

* [Nano Banana Pro 图片编辑 API](/api-capabilities/nano-banana-pro-image-edit)：本地图片与公网 URL 输入、最多 14 张参考图合成
* [Nano Banana 总览](/api-capabilities/nano-banana-image)：五个模型对比、两种调用方式与共用代码
* [Nano Banana 2 API](/api-capabilities/nano-banana2-image)：0.5K–4K、14 种比例，单价更低
* [Nano Banana 2 Lite API](/api-capabilities/nano-banana-2-lite-api)：只需 1K 时的轻量模型
* [Gemini 协议](/api-reference/gemini)：原生请求结构与 SDK 配置
* [Google 图像生成文档](https://ai.google.dev/gemini-api/docs/image-generation)：比例、像素尺寸、参考图上限、思考模式与文字渲染建议
* [Google generateContent 参考](https://ai.google.dev/api/generate-content)：`imageConfig`、`googleSearch`、`groundingMetadata` 等字段定义


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