> ## 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 API：Gemini 图像模型总览与接入
> 比较老张API五个 Nano Banana 模型的 ID、单价、分辨率与比例，说明两种调用方式，并提供共用的请求与保存代码。
老张API提供 Google 当前的 Gemini 图像模型系列 Nano Banana 共五个模型，都按次计费，只需老张API密钥，不需要 Google 账号。本页帮你选模型和调用方式，并提供各模型页共用的请求与保存代码。
## 模型对比
| 模型 | 模型 ID | 每次价格 | 适用场景 |
| - | - | - | - |
| [Nano Banana 2 Lite](/api-capabilities/nano-banana-2-lite-api) | `gemini-3.1-flash-lite-image` | \$0.025 | 1K 批量任务、快速迭代 |
| [Nano Banana 2.1](/api-capabilities/nano-banana-2-1-image) | `gemini-nano-banana-2.1` | \$0.045 | 新项目首选，1K–4K、文字排版 |
| [Nano Banana 2](/api-capabilities/nano-banana2-image) | `gemini-3.1-flash-image` | \$0.055 | 需要 0.5K，或已接入的通用生产 |
| [Nano Banana Pro](/api-capabilities/nano-banana-pro-image) | `gemini-3-pro-image` | \$0.09 | 复杂构图、专业成片 |
| Nano Banana（Standard） | `gemini-2.5-flash-image` | \$0.02 | 已过 Google 停止日期，暂时仍可调用，尽快迁移 |
分辨率、比例与参考图数量：
| 模型 | 分辨率 | 比例 | 参考图 |
| - | - | - | - |
| Nano Banana 2 Lite | 1K | 10 种 | 最多 14 张 |
| Nano Banana 2.1 | 1K–4K | 14 种 | 最多 14 张 |
| Nano Banana 2 | 0.5K–4K | 14 种 | 最多 14 张 |
| Nano Banana Pro | 1K–4K | 10 种 | 最多 14 张 |
| Nano Banana（Standard） | 1K | 10 种（仅 Gemini 原生格式） | 建议不超过 3 张 |
价格来自 2026 年 10 月 7 日公开价格配置，调用前请在[模型与价格](/models)确认最新单价。
* Standard 是系列中最早的 Nano Banana（`gemini-2.5-flash-image`），本站这样标注，以便与系列名区分。
* 五个模型都可以用 OpenAI 兼容格式或 Gemini 原生格式调用，区别见[两种调用方式](#两种调用方式)。需要指定比例或 2K、4K 分辨率时，使用 Gemini 原生格式。
* 比例和分辨率通过 Gemini 原生格式的 `aspectRatio`、`imageSize` 设置，具体取值见各模型页。Standard 只输出约 1K，不能传 `imageSize`。OpenAI 兼容格式下文生图输出 1K：Nano Banana 2.1 的画幅由模型按内容决定，其他模型为 1:1 的 1024×1024。
* 参考图数量来自 [Google 图像生成文档](https://ai.google.dev/gemini-api/docs/image-generation)：Standard 在输入不超过 3 张图时效果最好；Nano Banana 2 Lite 不针对多参考图和多轮连续编辑优化。
* 编辑图片的完整说明见 [Nano Banana 图片编辑 API（Standard）](/api-capabilities/nano-banana-image-edit)和 [Nano Banana Pro 图片编辑 API](/api-capabilities/nano-banana-pro-image-edit)；Nano Banana 2.1、2 与 2 Lite 的编辑示例在各自的模型页。
* 新项目一般从 Nano Banana 2.1 开始，只要 1K 小图时选 Nano Banana 2 Lite。
* Google 对 `gemini-2.5-flash-image` 停止日期的说法不一致：[Google 弃用页](https://ai.google.dev/gemini-api/docs/deprecations)截至 2026 年 10 月 8 日列为 2027 年 3 月 15 日，[价格页](https://ai.google.dev/gemini-api/docs/pricing)仍保留 2026 年 10 月 2 日停止的旧提示。截至 2026 年 10 月 5 日老张API仍可调用该模型、价格不变，但不保证继续提供的期限。已接入 Standard 的项目请尽快迁移，改法见 [Standard 图片编辑中的迁移说明](/api-capabilities/nano-banana-image-edit#迁移到新模型)。
五个模型的共同点：
* 模型来自 Google 官方渠道，不需要 Google 账号，只用老张API密钥。
* 按次线路以固定单价计费，分辨率、思考级别、参考图数量和生成 / 编辑都不改变单价，所以 2K、4K 出图低于 Google 按 token 计费的价格。
* 每次请求一张图，多张分多次请求。
* 平台不限制并发，`429` 来自上游容量，见[并发与 429](/faq/api-concurrency)。
* HTTP 200 无图扣一次，429、5xx 未进入生成不扣费，三个家族的对照见[扣费与失败规则](/api-capabilities/image-billing-and-failures)。
## 两种调用方式
两种格式使用同一个老张API密钥，主机都是 `https://api.laozhang.ai`：
| 项目 | OpenAI 兼容格式 | Gemini 原生格式 |
| - | - | - |
| 请求 | `POST /v1/chat/completions` | `POST /v1beta/models/{model}:generateContent` |
| 模型 ID | 请求体的 `model` 字段 | URL 中的 `{model}` |
| 比例与分辨率 | 不能设置 | `generationConfig.imageConfig` 的 `aspectRatio`、`imageSize` |
| 输入图片 | `image_url`：公网 URL 或 data URL | `inlineData`：`mimeType` 与 Base64 数据 |
| 返回图片 | `choices[0].message.content` 中的 data URL | `candidates[0].content.parts[]` 中的 `inlineData` |
| 认证 | `Authorization: Bearer` | `Authorization: Bearer` 或 `x-goog-api-key` |
**OpenAI 兼容格式**适合已经使用 OpenAI SDK 的项目：
* 把 SDK 的 `base_url` 设为 `https://api.laozhang.ai/v1`，`model` 换成 Nano Banana 模型 ID。
* 图片以 data URL（`data:image/png;base64,...`）的形式出现在返回的 `message.content` 中，前后可能带有 Markdown 图片语法等文字。
* 解析时直接查找 data URL，并按其中的类型保存为 PNG、JPEG 或 WebP 文件。
**Gemini 原生格式**可以设置比例和分辨率，也适合沿用 Gemini 请求结构或 Google Gen AI SDK 的项目，SDK 配置见 [Gemini 协议](/api-reference/gemini)。响应中的图片结构如下：
```json theme={null}
{
"candidates": [{
"content": {
"role": "model",
"parts": [
{"inlineData": {"mimeType": "image/png", "data": "iVBORw0KGgo..."}}
]
},
"finishReason": "STOP"
}]
}
```
`parts` 中也可能有文字块；逐个检查内容块，按 `inlineData.mimeType` 解码保存图片。
`imageSize` 使用大写 K，例如 `2K`；部分模型会拒绝小写的 `2k`。
两种格式都推荐使用 `Authorization: Bearer $LAOZHANG_API_KEY` 请求头。不要把密钥写进 URL 查询参数（例如 `?key=`），URL 容易被日志、代理和浏览器历史记录下来。
## 计费规则
老张API的 Nano Banana 只提供按次计费：每个模型一个单价，不随输出分辨率、思考级别、参考图数量或生成 / 编辑而变化。唯一的额外费用是 Google 搜索接地，按检索次数另计，见下文。
Google 官方按 tokens 计费，输出分辨率越高、思考 tokens 越多，费用越高。下表对比 2026 年 10 月 7 日老张API公开价格配置与 [Google 官方价格](https://ai.google.dev/gemini-api/docs/pricing)：
| 模型 | 老张API（按次） | Google 官方（每张图片输出） |
| - | -: | - |
| `gemini-3-pro-image`（Pro） | \$0.09 | 1K / 2K \$0.134，4K \$0.24 |
| `gemini-nano-banana-2.1`（Nano Banana 2.1） | \$0.045 | 1K \$0.0336，2K \$0.0504，4K \$0.113 |
| `gemini-3.1-flash-image`（Nano Banana 2） | \$0.055 | 0.5K \$0.045，1K \$0.067，2K \$0.101，4K \$0.151 |
| `gemini-3.1-flash-lite-image`（2 Lite） | \$0.025 | 1K \$0.0336 |
| `gemini-2.5-flash-image`（Standard） | \$0.02 | \$0.039 |
Google 官方价格取付费层级的标准价格，不含 Batch 等折扣方式；表中按每张输出图片折算，官方另按输入与思考 tokens 计费。
在 Google 官方计费下，4K 输出和 `high` 思考级别都会提高单次成本，在老张API仍是同一个按次价格；只有两种情况下官方的单张输出价格低于老张API的按次价：Nano Banana 2 输出 0.5K，Nano Banana 2.1 输出 1K。
在[令牌管理](https://api.laozhang.ai/token)新建或编辑令牌时，计费模式选择「按量优先」（推荐）或「按次计费」，然后保存。按量优先的令牌可以同时调用按量和按次计费的模型，按次计费的令牌只能调用按次计费的模型；各计费模式的区别见[计费与价格](/pricing)。
每次调用的状态和实际扣费记录在[调用日志](/faq/call-logs)中：
* **HTTP 200 但没有图片：按一次调用扣费。** 上游返回 HTTP 200 即视为调用完成，生成和编辑都一样。老张API不审查请求和生成内容，不按是否返回图片区分计费。原因与避免方法见[避免没有图片的扣费](#避免没有图片的扣费)。
* **客户端超时**：服务端可能已经生成完成并计费。重试前先在调用日志中确认请求状态，避免重复生成、重复扣费。
* **请求被拒绝**：返回 429 或 503、没有进入生成的请求，通常不扣费。
* **Google 搜索接地：每次检索另收 \$0.014。** 开启 `googleSearch` 的请求，在按次单价之外按实际检索次数计费，单价与 Google 官方每 1000 次 \$14 相同，适用于 Nano Banana 2.1、2 和 Pro。
* 检索几次由模型决定，同样的提示词每次也可能不同；调用日志会写明本次的检索次数和费用。
* 例如 Nano Banana 2.1 一次请求检索 2 次，共扣 \$0.045 + 2 × \$0.014 = \$0.073。
### 避免没有图片的扣费
HTTP 200 但没有图片，常见原因有两种：
* **提示词没有要求出图**：提示词只描述了需求，没有写明「生成一张图片」或「返回修改后的图片」，模型可能只做推理，最后只返回文字或空结果。
* **内容触发上游安全策略**：提示词或参考图涉及版权 IP、敏感人物或敏感内容，Google 不生成图片，也不返回错误码。同样的内容原样重试，通常仍会被拦截，每次都会扣费。
常会触发 Google 安全策略的内容：
* 色情、暴力、血腥或仇恨内容，包括暗示性的擦边内容；
* 去除图片上的水印；
* 迪士尼、漫威、任天堂等知名版权角色；
* 涉及未成年人的不当内容；
* 明星、政治人物等公众人物；
* 修改订单截图、票据、价格标签等金融信息；
* 给真人换装或换脸。
Google 的过滤有一定随机性，同一提示词有时能出图、有时被拦截，规则也会随上游调整而变化。被拦截时返回的通常是一段拒绝说明文字，而不是错误码。
批量调用前，在客户端做好以下处理：
1. 在提示词中明确要求生成或修改图片。
2. 提交前自行检查提示词和参考图，去掉可能触发安全策略的内容。
3. 响应中没有 `candidates`，或 `parts` 中没有 `inlineData`，都当作没有出图；有返回结果时，读取 `finishReason` 和返回的文字判断原因。
4. 不要自动重试没有图片的响应，修改提示词或参考图后再提交。429、5xx 仍可按退避策略重试。
## 共用代码
先设置密钥并安装依赖：
```bash theme={null}
export LAOZHANG_API_KEY="替换为你的老张API密钥"
python -m pip install requests
```
把下面的代码保存为 `nano_banana.py`，本页和各 Nano Banana 模型页的 Python 示例都会导入它：
* `post()`：发送带鉴权的请求
* `read_image()`：读取本地图片
* `save_images()`：把两种格式的响应保存为图片文件
```python theme={null}
"""Nano Banana 共用函数：发送请求、读取本地图片、保存返回的图片。"""
import base64
import json
import os
import re
import sys
from pathlib import Path
import requests
API_BASE = "https://api.laozhang.ai"
MIME_TYPES = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp"}
EXTENSIONS = {"png": "png", "jpeg": "jpg", "jpg": "jpg", "webp": "webp"}
def post(path, payload):
"""发送 JSON 请求；HTTP 状态不是 200 时显示错误正文并退出。"""
response = requests.post(
API_BASE + path,
headers={"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"},
json=payload,
timeout=300,
)
if response.status_code != 200:
raise SystemExit(f"HTTP {response.status_code}：{response.text[:1000]}")
return response.json()
def read_image(path):
"""读取本地 PNG、JPEG 或 WebP 图片，返回 (MIME 类型, Base64 字符串)。"""
path = Path(path)
mime = MIME_TYPES.get(path.suffix.lower())
if mime is None:
raise SystemExit(f"只支持 PNG、JPEG、WebP 图片：{path}")
return mime, base64.b64encode(path.read_bytes()).decode("ascii")
def save_images(result, prefix):
"""保存 OpenAI 兼容或 Gemini 原生响应中的全部图片，返回文件名列表。"""
if "choices" in result:
# OpenAI 兼容格式：图片是 message.content 里的 data URL
content = str(result["choices"][0]["message"].get("content") or "")
images = re.findall(r"data:image/(png|jpe?g|webp);base64,([A-Za-z0-9+/=]+)", content)
else:
# Gemini 原生格式：图片在 candidates[].content.parts[].inlineData 中
images = [
(part["inlineData"]["mimeType"].split("/")[-1], part["inlineData"]["data"])
for candidate in result.get("candidates") or []
for part in (candidate.get("content") or {}).get("parts") or []
if "inlineData" in part and not part.get("thought")
]
if not images:
raise SystemExit("响应中没有图片：" + json.dumps(result, ensure_ascii=False)[:1000])
filenames = []
for index, (kind, data) in enumerate(images, start=1):
filename = f"{prefix}-{index}.{EXTENSIONS.get(kind, kind)}"
Path(filename).write_bytes(base64.b64decode(data + "=" * (-len(data) % 4)))
print("已保存", filename)
filenames.append(filename)
return filenames
if __name__ == "__main__":
if len(sys.argv) != 3:
raise SystemExit("用法：python nano_banana.py 响应文件.json 输出文件前缀")
save_images(json.loads(Path(sys.argv[1]).read_text(encoding="utf-8")), sys.argv[2])
```
在命令行中运行 `python nano_banana.py response.json output`，可以把 cURL 保存的响应解码为 `output-1.png` 等文件，扩展名随实际图片格式变化。没有图片时，脚本会显示错误或文字内容。
## Standard（gemini-2.5-flash-image）
这是 Nano Banana 系列的第一个模型，本节供已接入的项目迁移前维护使用。`gemini-2.5-flash-image` 已被 Google 弃用：[Google 弃用页](https://ai.google.dev/gemini-api/docs/deprecations)现列的停止日期为 2027 年 3 月 15 日，价格页仍写 2026 年 10 月 2 日。截至 2026 年 10 月 5 日老张API仍可调用，但随时可能停止。
下面的示例使用 OpenAI 兼容格式，文生图输出 1024×1024，并导入[共用代码](#共用代码)中的 `nano_banana.py`。
### 生成图片
在提示词中明确要求生成图片，并描述主体、场景和风格：
```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-2.5-flash-image",
"stream": false,
"messages": [
{
"role": "user",
"content": "生成一张图片：清晨湖边的小木屋，薄雾，柔和逆光，写实摄影风格"
}
]
}' \
-o standard-generate.json
python nano_banana.py standard-generate.json standard-generate
```
```python theme={null}
from nano_banana import post, save_images
result = post("/v1/chat/completions", {
"model": "gemini-2.5-flash-image",
"stream": False,
"messages": [{
"role": "user",
"content": "生成一张图片：清晨湖边的小木屋，薄雾，柔和逆光，写实摄影风格",
}],
})
save_images(result, "standard-generate")
```
成功后当前目录会出现 `standard-generate-1.png` 等文件。使用 OpenAI SDK 时：
1. 调用 `client.chat.completions.create()`，传入相同的 `model` 和 `messages`。
2. 把 `response.model_dump()` 传给 `save_images()`。
### 编辑图片
把编辑指令和图片放在同一条 user 消息中，本地图片先转成 data URL。下面编辑上一步生成的图片（文件名以实际保存的为准）：
```python theme={null}
from nano_banana import post, read_image, save_images
mime, data = read_image("standard-generate-1.png") # 替换为你的图片路径
result = post("/v1/chat/completions", {
"model": "gemini-2.5-flash-image",
"stream": False,
"messages": [{
"role": "user",
"content": [
{"type": "text", "text": "把背景换成雪后的松林，保留小木屋的结构和颜色"},
{"type": "image_url", "image_url": {"url": f"data:{mime};base64,{data}"}},
],
}],
})
save_images(result, "standard-edit")
```
成功后会得到 `standard-edit-1.png` 等文件。cURL 写法、多图合成、公网图片 URL 输入，以及把编辑请求迁移到 Nano Banana 2 的改法，见 [Nano Banana 图片编辑 API（Standard）](/api-capabilities/nano-banana-image-edit)。
## 请求失败或没有图片
| 现象 | 处理方法 |
| - | - |
| 401 | 检查 `Authorization` 头和 API Key，不要使用账号 AccessToken |
| 400 | 检查 JSON 结构、图片 MIME 类型与 Base64 数据，以及比例、分辨率是否在该模型的可选范围内 |
| 404 或模型不可用 | 核对请求路径、完整模型 ID 和令牌分组 |
| 429、5xx 或超时 | 先查看调用日志确认请求状态，再决定是否重试 |
| HTTP 200 但没有图片 | 已按一次调用扣费，不要原样重试；查看返回的文字和 `finishReason`，按[避免没有图片的扣费](#避免没有图片的扣费)修改后再提交 |
## 常见问题
### 新项目该选哪个 Nano Banana 模型？
先用 Nano Banana 2.1（`gemini-nano-banana-2.1`）。它是 Nano Banana 2 的更新版，支持 1K–4K 输出、14 种比例和最多 14 张参考图，文字排版更准，单价也更低。其他情况：
* 需要 0.5K 预览图：选 Nano Banana 2。
* 只需要 1K、更看重单价和速度：选 Nano Banana 2 Lite。
* 复杂构图、精确文字渲染或品牌细节要求高：选 Nano Banana Pro。
* 不要在 Standard（`gemini-2.5-flash-image`）上开始新项目：Google 已弃用该模型，停止日期的说法前后不一（弃用页为 2027 年 3 月 15 日，价格页仍写 2026 年 10 月 2 日），老张API暂时仍可调用，但随时可能停止。
已接入 Standard 的项目，1K 单图编辑可以迁移到 Nano Banana 2 Lite，依赖多图合成的迁移到 Nano Banana 2.1 或 Nano Banana 2（两者请求写法相同），改法见 [Standard 图片编辑中的迁移说明](/api-capabilities/nano-banana-image-edit#迁移到新模型)。
### OpenAI 兼容格式能出 16:9 或 4K 吗？
不能。OpenAI 兼容格式没有比例和分辨率参数。
需要 16:9、9:16 等比例时，用 Gemini 原生格式调用 Nano Banana 2 Lite、2.1、2 或 Pro；需要 2K、4K 时，选择 Nano Banana 2.1、2 或 Pro。
### 分辨率、参考图数量或编辑会影响单价吗？
不会。每个模型只有一个按次单价，同一个模型输出 0.5K 还是 4K、思考级别用默认还是 `high`、带 1 张还是 14 张参考图、生成还是编辑，每次调用的价格都相同。只有开启搜索接地时，会按检索次数每次另收 \$0.014。与 Google 官方价格的对比见[计费规则](#计费规则)。
### 请求失败、超时或没有出图，会扣费吗？
HTTP 200 但没有图片会按一次调用扣费，包括提示词没有要求出图、内容被上游安全策略拦截的情况。客户端超时也可能已经扣费，返回 429 或 503、没有进入生成的请求通常不扣费。
每次调用的状态和扣费见[调用日志](/faq/call-logs)，各情况的处理方法见[计费规则](#计费规则)。
### 一次请求能生成多张图吗？
不要依赖这种用法。Google 说明，模型不一定按提示词要求的数量输出图片。需要多张图时，分别发送多次请求，每次调用单独计费。
反过来，一个响应里偶尔会出现多张图片：Gemini 3 图像模型在思考时会生成临时图片检验构图，这些图片可能和最终结果一起返回，其中最后一张是最终结果。
[共用代码](#共用代码)中的 `save_images()` 按顺序保存全部图片，编号最大的文件就是最后一张。
### 可以直接用中文提示词吗？
可以。Google 列出的最佳表现语言包括英语、简体中文（zh-CN）、日语、韩语等 15 种语言区域，本站示例也使用中文提示词。其他语言也能使用，但效果可能不够稳定。
### 生成的图片带水印吗？
带。Google 说明，所有 Nano Banana 模型生成的图片都带有 SynthID 数字水印。SynthID 直接嵌入图片，人眼无法察觉，用于识别 AI 生成的内容。
### 支持哪些输入图片格式？
Google 列出的图片输入格式为 PNG、JPEG、WebP、HEIC 和 HEIF。本站示例和[共用代码](#共用代码)中的 `read_image()` 只处理 PNG、JPEG 和 WebP，HEIC、HEIF 照片可以先转成 JPEG。
无论哪种格式，`mimeType` 或 data URL 前缀都要与文件的实际格式一致。图片转成 Base64 后体积会增加约三分之一，很大的照片先缩小再上传，可以缩短请求时间。
### 纯白背景出现黑点或脏块怎么办？
把提示词里的纯白背景换成其他浅色背景。Nano Banana 走 Google AI Studio 线路，出纯白背景图时，大面积白色区域偶尔会出现黑点、脏块、灰白雾化或偏色，高峰时段更常见。可以改成：
* 浅灰：`light gray background, #F5F5F5`
* 米色：`beige background, #F5F0E5`
* 淡蓝：`light blue background, #E8F0F8`
只改背景描述，不影响主体的颜色。确实需要纯白底时，可以在自己的后期处理中替换背景色。有瑕疵的图片同样按一次调用扣费，批量出图前先用几张样图确认效果。
## 相关文档
* [Nano Banana 图片编辑 API（Standard）](/api-capabilities/nano-banana-image-edit)：`gemini-2.5-flash-image` 的编辑写法与迁移
* [Nano Banana 2 Lite API](/api-capabilities/nano-banana-2-lite-api)：1K 生成与编辑、10 种比例
* [Nano Banana 2.1 API](/api-capabilities/nano-banana-2-1-image)：1K–4K、14 种比例、三档思考级别
* [Nano Banana 2 API](/api-capabilities/nano-banana2-image)：0.5K–4K、14 种比例
* [Nano Banana Pro API](/api-capabilities/nano-banana-pro-image)：1K–4K 生成与搜索接地
* [Nano Banana Pro 图片编辑 API](/api-capabilities/nano-banana-pro-image-edit)：多图合成、公网 URL 输入与 4K 编辑
* [图像 API 选型与价格](/api-capabilities/image-generation-guide)：与其他图像模型比较
* [Gemini 协议](/api-reference/gemini)：原生请求结构与 Google Gen AI SDK 配置
* [模型与价格](/models)：当前模型 ID 与单价
* [Google 图像生成文档](https://ai.google.dev/gemini-api/docs/image-generation)：模型能力、比例、参考图上限、支持语言与 SynthID 水印
* [Google 图像理解文档](https://ai.google.dev/gemini-api/docs/image-understanding)：支持的输入图片格式
* [Google Gemini API 价格](https://ai.google.dev/gemini-api/docs/pricing)：各图像模型的官方价格与搜索接地计费方式
* [Google generateContent 参考](https://ai.google.dev/api/generate-content)：`imageConfig` 等字段定义
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.