nano-banana

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Nano Banana - Gemini Image Generation

Nano Banana - Gemini图像生成

Generate and edit images from text prompts via Google's Gemini image generation API.

通过Google的Gemini图像生成API，从文本提示生成和编辑图片。

When to Use

适用场景

User requests image generation, creation, or production from a text description
Editing existing images with text instructions
Style-transfer: generate new images that match the aesthetic of a reference
Creating illustrations for presentations, articles, thumbnails, social posts
Batch variations of the same concept

用户需要根据文本描述生成、创建或制作图片
使用文本指令编辑现有图片
风格迁移：生成与参考图美学风格匹配的新图片
为演示文稿、文章、缩略图、社交帖子创建插图
批量生成同一概念的变体图片

First-Time Setup

首次设置

bash

scripts/nano_banana.py init

Wizard checks dependencies (sops, age, magick), verifies the API key, and saves defaults to

~/.config/nano-banana/config.yaml

bash

scripts/nano_banana.py init

设置向导会检查依赖项（sops、age、magick），验证API密钥，并将默认配置保存到

~/.config/nano-banana/config.yaml

。

Quick Start

快速开始

bash

undefined

bash

undefined

Simple generation

简单生成

scripts/nano_banana.py "a minimalist illustration of a rocket" ./rocket.png

With style preset

使用风格预设

scripts/nano_banana.py --preset editorial "interconnected nodes" ./nodes.png

YouTube thumbnail (auto-cropped to 1280x720)

YouTube缩略图（自动裁剪为1280x720）

scripts/nano_banana.py --preset grain --platform youtube "coffee on desk" ./thumb.png

Generate 4 variants + contact sheet

生成4个变体图片+联络图

scripts/nano_banana.py --preset wireframe "a crystal" ./crystal.png --n 4

Edit existing image

编辑现有图片

scripts/nano_banana.py --edit ./old.png "make the background deep teal" ./new.png

Style reference (match aesthetic of existing image)

风格参考（匹配现有图片的美学风格）

scripts/nano_banana.py --reference ./style.png "a new mountain landscape" ./mountain.png

Re-roll last prompt

重新生成上一个提示

scripts/nano_banana.py again

View history

查看历史记录

scripts/nano_banana.py history -n 10

undefined

scripts/nano_banana.py history -n 10

undefined

Requirements

依赖要求

GEMINI_API_KEY

— auto-decrypted from

secrets.enc.yaml

via SOPS + age. Fallback:

export GEMINI_API_KEY=...

```
sops
```
,
```
age
```
— for key decryption
```
magick
```
(ImageMagick) — for platform fit + contact sheets
```
python3
```
with
```
pyyaml
```

GEMINI_API_KEY

— 从

secrets.enc.yaml

通过SOPS + age自动解密。备选方案：

export GEMINI_API_KEY=...

```
sops
```
、
```
age
```
— 用于密钥解密
```
magick
```
（ImageMagick） — 用于平台适配尺寸+联络图生成
安装
```
pyyaml
```
的
```
python3
```
环境

Models

模型

Model	Alias	Nano Banana Name	Use When
`gemini-3.1-flash-image-preview` (default)	`flash`	Nano Banana 2	Best instruction following, fast
`gemini-3-pro-image-preview`	`pro`	Nano Banana Pro	Highest quality, text in images
`gemini-2.5-flash-image`	`flash-2.5`	Nano Banana (original)	Legacy

Use via

--model flash|pro|flash-2.5

or full ID.

模型	别名	Nano Banana名称	适用场景
`gemini-3.1-flash-image-preview` （默认）	`flash`	Nano Banana 2	指令理解能力最佳，速度快
`gemini-3-pro-image-preview`	`pro`	Nano Banana Pro	画质最高，支持图片中生成文字
`gemini-2.5-flash-image`	`flash-2.5`	Nano Banana（初代）	旧版本兼容

通过

--model flash|pro|flash-2.5

或完整模型ID调用。

Style Presets

风格预设

bash

scripts/nano_banana.py list-presets
scripts/nano_banana.py --preset editorial "your subject" out.png

Preset	Style
`editorial`	Thin lines on black, muted palette, technical diagram feel
`blueprint`	White/cyan lines on dark navy, engineering drawing
`ink`	Japanese sumi-e ink wash, organic brushstrokes, monochrome
`risograph`	Flat colors, grain, terracotta + sage, zine aesthetic
`wireframe`	3D wireframe mesh, glowing edges on black
`constellation`	Star map dots connected by faint lines, celestial
`brutalist`	Bold shapes, thick borders, hard shadows, flat colors
`grain`	Film grain photo, high ISO, warm cinematic tones

Defined in

presets.yaml

— edit to add your own.

bash

scripts/nano_banana.py list-presets
scripts/nano_banana.py --preset editorial "your subject" out.png

预设	风格
`editorial`	黑色背景细线条，低饱和度配色，技术图表风格
`blueprint`	深蓝色背景白/青色线条，工程图纸风格
`ink`	日本水墨风格，有机笔触，单色
`risograph`	平涂色彩，颗粒感，赤陶色+鼠尾草绿，zine刊物美学
`wireframe`	3D线框网格，黑色背景发光边缘
`constellation`	星图点与淡线连接，天体风格
`brutalist`	大胆形状，粗边框，硬阴影，平涂色彩
`grain`	胶片颗粒感照片，高ISO，暖色调电影质感

风格预设定义在

presets.yaml

中，可编辑添加自定义预设。

Platform Presets

平台预设

bash

scripts/nano_banana.py list-platforms
scripts/nano_banana.py --platform youtube "your subject" out.png

Generated image is automatically resized + center-cropped to target dimensions.

Platform	Size
`youtube`	1280×720
`youtube-short`	1080×1920
`slides`	1920×1080
`blog`	1200×630
`x`	1600×900
`square`	1080×1080
`story`	1080×1920
`pinterest`	1000×1500

bash

scripts/nano_banana.py list-platforms
scripts/nano_banana.py --platform youtube "your subject" out.png

生成的图片会自动调整尺寸并居中裁剪至目标尺寸。

平台	尺寸
`youtube`	1280×720
`youtube-short`	1080×1920
`slides`	1920×1080
`blog`	1200×630
`x`	1600×900
`square`	1080×1080
`story`	1080×1920
`pinterest`	1000×1500

Features

功能特性

Variants + Contact Sheet

变体图片+联络图

--n N

generates N variants in parallel and assembles them into a contact sheet:

bash

scripts/nano_banana.py --preset ink "mountain" ./mt.png --n 6

--n N

并行生成N个变体图片，并将它们组合成一张联络图：

bash

scripts/nano_banana.py --preset ink "mountain" ./mt.png --n 6

Creates mt-01.png ... mt-06.png + mt-contact.png

生成mt-01.png ... mt-06.png + mt-contact.png

undefined

undefined

Edit Mode

编辑模式

Pass an existing image and the prompt becomes the edit instruction:

bash

scripts/nano_banana.py --edit ./thumb.png "remove the watermark, warmer colors" ./clean.png

传入现有图片，提示文本将作为编辑指令：

bash

scripts/nano_banana.py --edit ./thumb.png "remove the watermark, warmer colors" ./clean.png

Reference Images (Style Anchor)

参考图片（风格锚定）

Use one or more reference images to guide the aesthetic without editing them:

bash

scripts/nano_banana.py --reference ./episode1.png --reference ./episode2.png \
  "episode 3: data drift" ./ep3.png

使用一张或多张参考图片引导生成图片的美学风格，无需编辑参考图本身：

bash

scripts/nano_banana.py --reference ./episode1.png --reference ./episode2.png \
  "episode 3: data drift" ./ep3.png

Projects + Metadata

项目分类+元数据

Organize outputs by project:

bash

scripts/nano_banana.py --project lab-04/meeting-02 --preset editorial "MCP loops" ./overlay.png

按项目组织输出文件：

bash

scripts/nano_banana.py --project lab-04/meeting-02 --preset editorial "MCP loops" ./overlay.png

Saves to ~/nano-banana/outputs/lab-04/meeting-02/20260414-<subject>.png + .json sidecar

保存至~/nano-banana/outputs/lab-04/meeting-02/20260414-<subject>.png + 配套.json元数据文件

undefined

undefined

Re-roll + History

重新生成+历史记录

bash

scripts/nano_banana.py again              # rerun last prompt
scripts/nano_banana.py history -n 20      # show last 20 generations
scripts/nano_banana.py history --project lab-04

bash

scripts/nano_banana.py again              # 重新运行上一个提示
scripts/nano_banana.py history -n 20      # 显示最近20次生成记录
scripts/nano_banana.py history --project lab-04

Dry Run

试运行

Preview the composed prompt without calling the API:

bash

scripts/nano_banana.py --preset editorial --platform youtube "subject" --dry-run

预览组合后的提示文本，不调用API：

bash

scripts/nano_banana.py --preset editorial --platform youtube "subject" --dry-run

Transient Errors & Retry

临时错误与重试

The API occasionally returns

500/INTERNAL

or empty candidates. The script retries up to 4 times with exponential backoff (2s, 4s, 8s, 16s). Permanent errors (4xx, safety violations) fail fast without retry.

API偶尔会返回

500/INTERNAL

错误或空结果。脚本会最多重试4次，采用指数退避策略（2秒、4秒、8秒、16秒）。永久错误（4xx、安全违规）会直接失败，不进行重试。

Prompt Tips

提示词技巧

Specify visual style: "photograph", "flat illustration", "watercolor", "3D render"
Include composition: "centered", "white background", "wide shot"
Name colors: "blue and white color scheme", "warm earth tones"
For text rendering, use
```
--model pro
```
and quote exact text:
```
'with the text "Hello"'
```

See

references/api_reference.md

for full API documentation.

指定视觉风格：比如“photograph”（照片）、“flat illustration”（扁平插画）、“watercolor”（水彩）、“3D render”（3D渲染）
包含构图要求：“centered”（居中）、“white background”（白色背景）、“wide shot”（宽幅镜头）
明确颜色：“blue and white color scheme”（蓝白配色）、“warm earth tones”（暖大地色调）
如需生成文字，使用
```
--model pro
```
并精确引用文字：
```
'with the text "Hello"'
```

完整API文档请查看

references/api_reference.md

。

Files

文件说明

```
scripts/nano_banana.py
```
— main CLI (Python)
```
scripts/generate_image.sh
```
— thin bash wrapper (back-compat)
```
presets.yaml
```
— style presets
```
platforms.yaml
```
— platform sizing presets
```
secrets.enc.yaml
```
— encrypted API key (SOPS + age)
```
~/.config/nano-banana/config.yaml
```
— user defaults (from
```
init
```
)
```
~/.config/nano-banana/history.jsonl
```
— generation log
```
~/.config/nano-banana/last.json
```
— last run (for
```
again
```
)

```
scripts/nano_banana.py
```
— 主CLI工具（Python编写）
```
scripts/generate_image.sh
```
— 轻量bash包装器（向后兼容）
```
presets.yaml
```
— 风格预设配置文件
```
platforms.yaml
```
— 平台尺寸预设配置文件
```
secrets.enc.yaml
```
— 加密的API密钥（SOPS + age）
```
~/.config/nano-banana/config.yaml
```
— 用户默认配置（来自
```
init
```
命令）
```
~/.config/nano-banana/history.jsonl
```
— 生成记录日志
```
~/.config/nano-banana/last.json
```
— 上一次运行记录（用于
```
again
```
命令）