nanobanana

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Nano Banana

A single Python entrypoint for Gemini-native Nano Banana image generation and editing, with model aliases, strict option validation, batch runs, and custom endpoint support.

一款基于Gemini原生的Nano Banana图像生成与编辑工具的Python统一入口，支持模型别名、严格参数验证、批量运行以及自定义端点功能。

Workflow

工作流程

Open references/config.md to choose environment variables and override order.
Open references/models-and-api.md to pick the right Nano Banana tier and check model-specific constraints.
Prefer
```
gemini-3.1-flash-image-preview
```
(
```
nanobanana-2
```
) unless you need either the fastest low-cost default (
```
nanobanana
```
) or the highest-fidelity reasoning model (
```
nanobanana-pro
```
).

Run

scripts/nanobanana.py generate

for one request or

scripts/nanobanana.py batch

for repeated variants.

Add
```
--dry-run
```
first when the main risk is the payload shape, endpoint, or model-specific option support.
Pass
```
--base-url
```
or
```
GEMINI_BASE_URL
```
when you need a custom Gemini-compatible gateway.
Add
```
--save-response <path>
```
on
```
generate
```
when you need the raw JSON body for debugging.

打开references/config.md选择环境变量及优先级覆盖规则。
打开references/models-and-api.md选择合适的Nano Banana版本，并查看模型特定约束。
除非你需要最快低成本的默认版本（
```
nanobanana
```
）或最高保真度的推理模型（
```
nanobanana-pro
```
），否则优先选择
```
gemini-3.1-flash-image-preview
```
（对应
```
nanobanana-2
```
）。

运行

scripts/nanobanana.py generate

执行单次请求，或运行

scripts/nanobanana.py batch

生成多个变体。

当主要风险在于请求负载格式、端点或模型特定参数支持时，先添加
```
--dry-run
```
参数进行预演。
当需要使用自定义Gemini兼容网关时，传入
```
--base-url
```
参数或设置
```
GEMINI_BASE_URL
```
环境变量。
在
```
generate
```
命令中添加
```
--save-response <path>
```
参数，可保存原始JSON响应体用于调试。

Commands

命令示例

Single text-to-image request:

powershell

python .\skills\nanobanana\scripts\nanobanana.py generate `
  --prompt "A retro-futurist product hero illustration for a developer tool" `
  --output .\out\hero.png `
  --model nanobanana-2 `
  --ratio 16:9 `
  --size 2K

Edit an existing image with two local references:

powershell

python .\skills\nanobanana\scripts\nanobanana.py generate `
  --prompt "Turn these references into a clean launch poster with legible title text" `
  --input-image .\refs\subject.png `
  --input-image .\refs\background.png `
  --output .\out\poster.png `
  --model nanobanana-pro `
  --ratio 4:5 `
  --size 2K

Use a custom Gemini-compatible gateway:

powershell

python .\skills\nanobanana\scripts\nanobanana.py generate `
  --prompt "A bold mascot sticker pack" `
  --output .\out\stickers.png `
  --base-url http://your-gateway.example.com/v1beta `
  --auth-mode bearer

Batch-generate five variants:

powershell

python .\skills\nanobanana\scripts\nanobanana.py batch `
  --prompt "Minimal app icon for a PDF workflow product" `
  --count 5 `
  --dir .\out\icons `
  --prefix icon `
  --model nanobanana `
  --ratio 1:1

Inspect the final request without sending it:

powershell

python .\skills\nanobanana\scripts\nanobanana.py generate `
  --prompt "An editorial illustration of AI agents at work" `
  --model nanobanana-2 `
  --output .\out\agents.png `
  --dry-run

单文本生成图像请求：

powershell

python .\skills\nanobanana\scripts\nanobanana.py generate `
  --prompt "A retro-futurist product hero illustration for a developer tool" `
  --output .\out\hero.png `
  --model nanobanana-2 `
  --ratio 16:9 `
  --size 2K

使用两张本地参考图编辑现有图像：

powershell

python .\skills\nanobanana\scripts\nanobanana.py generate `
  --prompt "Turn these references into a clean launch poster with legible title text" `
  --input-image .\refs\subject.png `
  --input-image .\refs\background.png `
  --output .\out\poster.png `
  --model nanobanana-pro `
  --ratio 4:5 `
  --size 2K

使用自定义Gemini兼容网关：

powershell

python .\skills\nanobanana\scripts\nanobanana.py generate `
  --prompt "A bold mascot sticker pack" `
  --output .\out\stickers.png `
  --base-url http://your-gateway.example.com/v1beta `
  --auth-mode bearer

批量生成5个变体：

powershell

python .\skills\nanobanana\scripts\nanobanana.py batch `
  --prompt "Minimal app icon for a PDF workflow product" `
  --count 5 `
  --dir .\out\icons `
  --prefix icon `
  --model nanobanana `
  --ratio 1:1

预演请求（不实际发送）：

powershell

python .\skills\nanobanana\scripts\nanobanana.py generate `
  --prompt "An editorial illustration of AI agents at work" `
  --model nanobanana-2 `
  --output .\out\agents.png `
  --dry-run

Rules

规则说明

```
--model
```
accepts the aliases
```
nanobanana
```
,
```
nanobanana-2
```
, and
```
nanobanana-pro
```
, or an exact Gemini model ID.

nanobanana

resolves to

gemini-2.5-flash-image

nanobanana-2

resolves to

gemini-3.1-flash-image-preview

, and

nanobanana-pro

resolves to

gemini-3-pro-image-preview

```
image_size
```
is only valid on Gemini 3 image models;
```
nanobanana
```
rejects
```
--size
```
.
```
512
```
resolution is only valid on
```
nanobanana-2
```
.
Process environment variables override
```
.env
```
; CLI flags override both.
Never print secrets.
```
generate
```
accepts repeated
```
--input-image
```
paths for image editing or multi-reference generation.

--base-url

should point to the Gemini API root such as

https://generativelanguage.googleapis.com/v1beta

, not directly to

/models/...

```
--auth-mode auto
```
uses
```
x-goog-api-key
```
for the official Google endpoint and sends both
```
Authorization: Bearer
```
and
```
x-goog-api-key
```
for custom endpoints to maximize gateway compatibility.

```
--model
```
参数接受别名
```
nanobanana
```
、
```
nanobanana-2
```
、
```
nanobanana-pro
```
，或精确的Gemini模型ID。

nanobanana

对应

gemini-2.5-flash-image

，

nanobanana-2

对应

gemini-3.1-flash-image-preview

，

nanobanana-pro

对应

gemini-3-pro-image-preview

。

```
image_size
```
仅在Gemini 3图像模型上有效；
```
nanobanana
```
版本不支持
```
--size
```
参数。
512分辨率仅在
```
nanobanana-2
```
版本上有效。
环境变量会覆盖
```
.env
```
文件配置；CLI参数会同时覆盖环境变量和
```
.env
```
配置。
绝不打印敏感信息。
```
generate
```
命令接受重复的
```
--input-image
```
路径，用于图像编辑或多参考图生成。

--base-url

应指向Gemini API根路径，例如

https://generativelanguage.googleapis.com/v1beta

，而非直接指向

/models/...

。

```
--auth-mode auto
```
在官方Google端点使用
```
x-goog-api-key
```
，在自定义端点同时发送
```
Authorization: Bearer
```
和
```
x-goog-api-key
```
，以最大化网关兼容性。

Resources

资源链接

Script: scripts/nanobanana.py
Config reference: references/config.md
Models and API reference: references/models-and-api.md

脚本：scripts/nanobanana.py
配置参考：references/config.md
模型与API参考：references/models-and-api.md