nano-banana-pro

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Nano Banana Pro Image Generation & Editing

Nano Banana Pro 图片生成与编辑

Generate new images or edit existing ones using Google's Nano Banana Pro API (Gemini 3 Pro Image).

使用Google的Nano Banana Pro API（Gemini 3 Pro Image）生成新图片或编辑现有图片。

Usage

使用方法

Run the script using absolute path (do NOT cd to skill directory first):

Generate new image:

bash

uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "your image description" --filename "output-name.png" [--resolution 1K|2K|4K] [--api-key KEY]

Edit existing image:

bash

uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "editing instructions" --filename "output-name.png" --input-image "path/to/input.png" [--resolution 1K|2K|4K] [--api-key KEY]

Important: Always run from the user's current working directory so images are saved where the user is working, not in the skill directory.

请使用绝对路径运行脚本（不要先切换到技能目录）：

生成新图片：

bash

uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "你的图片描述" --filename "输出名称.png" [--resolution 1K|2K|4K] [--api-key KEY]

编辑现有图片：

bash

uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "编辑指令" --filename "输出名称.png" --input-image "输入图片路径.png" [--resolution 1K|2K|4K] [--api-key KEY]

重要提示： 始终从用户当前工作目录运行脚本，这样图片会保存到用户的工作目录，而非技能目录。

Default Workflow (draft → iterate → final)

默认工作流程（草稿→迭代→最终版本）

Goal: fast iteration without burning time on 4K until the prompt is correct.

Draft (1K): quick feedback loop

uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "<draft prompt>" --filename "yyyy-mm-dd-hh-mm-ss-draft.png" --resolution 1K

Iterate: adjust prompt in small diffs; keep filename new per run
- If editing: keep the same
```
--input-image
```
  for every iteration until you’re happy.

Final (4K): only when prompt is locked

uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "<final prompt>" --filename "yyyy-mm-dd-hh-mm-ss-final.png" --resolution 4K

目标：快速迭代，在确定prompt合适之前，不要浪费时间生成4K图片。

草稿（1K）：快速反馈循环

uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "<草稿prompt>" --filename "yyyy-mm-dd-hh-mm-ss-draft.png" --resolution 1K

迭代：小幅调整prompt；每次运行使用新的文件名
- 如果是编辑操作：在满意之前，每次迭代都使用相同的
```
--input-image
```

最终版本（4K）：仅当prompt确定后使用

uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "<最终prompt>" --filename "yyyy-mm-dd-hh-mm-ss-final.png" --resolution 4K

Resolution Options

分辨率选项

The Gemini 3 Pro Image API supports three resolutions (uppercase K required):

1K (default) - ~1024px resolution
2K - ~2048px resolution
4K - ~4096px resolution

Map user requests to API parameters:

No mention of resolution →
```
1K
```
"low resolution", "1080", "1080p", "1K" →
```
1K
```
"2K", "2048", "normal", "medium resolution" →
```
2K
```
"high resolution", "high-res", "hi-res", "4K", "ultra" →
```
4K
```

Gemini 3 Pro Image API支持三种分辨率（K必须大写）：

1K（默认）- 约1024px分辨率
2K - 约2048px分辨率
4K - 约4096px分辨率

用户请求与API参数的映射：

未提及分辨率 →
```
1K
```
"低分辨率", "1080", "1080p", "1K" →
```
1K
```
"2K", "2048", "普通", "中等分辨率" →
```
2K
```
"高分辨率", "high-res", "hi-res", "4K", "ultra" →
```
4K
```

API Key

API密钥

The script checks for API key in this order:

```
--api-key
```
argument (use if user provided key in chat)
```
GEMINI_API_KEY
```
environment variable

If neither is available, the script exits with an error message.

脚本会按以下顺序查找API密钥：

```
--api-key
```
参数（如果用户在对话中提供了密钥）
```
GEMINI_API_KEY
```
环境变量

如果两者都不存在，脚本会退出并显示错误信息。

Preflight + Common Failures (fast fixes)

预检与常见问题快速修复

Preflight:

```
command -v uv
```
(must exist)
```
test -n \"$GEMINI_API_KEY\"
```
(or pass
```
--api-key
```
)
If editing:
```
test -f \"path/to/input.png\"
```

Common failures:
- ```
Error: No API key provided.
```
  → set
```
GEMINI_API_KEY
```
  or pass
```
--api-key
```
- ```
Error loading input image:
```
  → wrong path / unreadable file; verify
```
--input-image
```
  points to a real image
- “quota/permission/403” style API errors → wrong key, no access, or quota exceeded; try a different key/account

预检：

```
command -v uv
```
（必须存在）
```
test -n \"$GEMINI_API_KEY\"
```
（或传入
```
--api-key
```
）
如果是编辑操作：
```
test -f \"输入图片路径.png\"
```

常见错误：
- ```
Error: No API key provided.
```
  → 设置
```
GEMINI_API_KEY
```
  环境变量或传入
```
--api-key
```
  参数
- ```
Error loading input image:
```
  → 路径错误或文件不可读；确认
```
--input-image
```
  指向真实存在的图片
- “quota/permission/403”类API错误 → 密钥错误、无访问权限或配额用尽；尝试更换密钥/账号

Filename Generation

文件名生成

Generate filenames with the pattern:

yyyy-mm-dd-hh-mm-ss-name.png

Format:

{timestamp}-{descriptive-name}.png

Timestamp: Current date/time in format
```
yyyy-mm-dd-hh-mm-ss
```
(24-hour format)
Name: Descriptive lowercase text with hyphens
Keep the descriptive part concise (1-5 words typically)
Use context from user's prompt or conversation
If unclear, use random identifier (e.g.,
```
x9k2
```
,
```
a7b3
```
)

Examples:

Prompt "A serene Japanese garden" →
```
2025-11-23-14-23-05-japanese-garden.png
```

Prompt "sunset over mountains" →

2025-11-23-15-30-12-sunset-mountains.png

Prompt "create an image of a robot" →
```
2025-11-23-16-45-33-robot.png
```
Unclear context →
```
2025-11-23-17-12-48-x9k2.png
```

使用以下格式生成文件名：

yyyy-mm-dd-hh-mm-ss-name.png

格式：

{时间戳}-{描述性名称}.png

时间戳：当前日期/时间，格式为
```
yyyy-mm-dd-hh-mm-ss
```
（24小时制）
名称：简洁的小写描述性文本，用连字符分隔
描述部分保持简洁（通常1-5个词）
使用用户prompt或对话中的上下文信息
如果上下文不明确，使用随机标识符（例如
```
x9k2
```
,
```
a7b3
```
）

示例：

Prompt "宁静的日式花园" →
```
2025-11-23-14-23-05-japanese-garden.png
```

Prompt "山间日落" →

2025-11-23-15-30-12-sunset-mountains.png

Prompt "创建一张机器人的图片" →
```
2025-11-23-16-45-33-robot.png
```
上下文不明确 →
```
2025-11-23-17-12-48-x9k2.png
```

Image Editing

图片编辑

When the user wants to modify an existing image:

Check if they provide an image path or reference an image in the current directory
Use
```
--input-image
```
parameter with the path to the image
The prompt should contain editing instructions (e.g., "make the sky more dramatic", "remove the person", "change to cartoon style")
Common editing tasks: add/remove elements, change style, adjust colors, blur background, etc.

当用户想要修改现有图片时：

检查用户是否提供了图片路径或引用了当前目录中的图片
使用
```
--input-image
```
参数传入图片路径
Prompt中应包含编辑指令（例如"让天空更有氛围感", "移除人物", "改为卡通风格"）
常见编辑任务：添加/移除元素、更改风格、调整颜色、模糊背景等

Prompt Handling

Prompt处理

For generation: Pass user's image description as-is to

--prompt

. Only rework if clearly insufficient.

For editing: Pass editing instructions in

--prompt

(e.g., "add a rainbow in the sky", "make it look like a watercolor painting")

Preserve user's creative intent in both cases.

生成图片： 将用户的图片描述直接传入

--prompt

。仅当描述明显不充分时才进行修改。

编辑图片： 将编辑指令传入

--prompt

（例如"在天空中添加彩虹", "让它看起来像水彩画"）在两种情况下都要保留用户的创意意图。

Prompt Templates (high hit-rate)

高成功率Prompt模板

Use templates when the user is vague or when edits must be precise.

Generation template:
- “Create an image of: <subject>. Style: <style>. Composition: <camera/shot>. Lighting: <lighting>. Background: <background>. Color palette: <palette>. Avoid: <list>.”
Editing template (preserve everything else):
- “Change ONLY: <single change>. Keep identical: subject, composition/crop, pose, lighting, color palette, background, text, and overall style. Do not add new objects. If text exists, keep it unchanged.”

当用户的需求模糊或编辑需要精准时，使用以下模板。

生成模板：
- “创建一张图片：<主体>。风格：<风格>。构图：<镜头/视角>。光线：<光线效果>。背景：<背景>。调色板：<调色板>。避免：<列表>。”
编辑模板（保留其他所有元素）：
- “仅修改：<单一修改内容>。保持以下元素完全不变：主体、构图/裁剪、姿势、光线、调色板、背景、文字和整体风格。不要添加新物体。如果存在文字，保持其不变。”

Output

输出

Saves PNG to current directory (or specified path if filename includes directory)
Script outputs the full path to the generated image
Do not read the image back - just inform the user of the saved path

将PNG图片保存到当前目录（如果文件名包含目录，则保存到指定路径）
脚本会输出生成图片的完整路径
不要读取图片内容 - 只需告知用户保存路径即可

Examples

示例

Generate new image:

bash

uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "A serene Japanese garden with cherry blossoms" --filename "2025-11-23-14-23-05-japanese-garden.png" --resolution 4K

Edit existing image:

bash

uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "make the sky more dramatic with storm clouds" --filename "2025-11-23-14-25-30-dramatic-sky.png" --input-image "original-photo.jpg" --resolution 2K

生成新图片：

bash

uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "宁静的日式花园，开满樱花" --filename "2025-11-23-14-23-05-japanese-garden.png" --resolution 4K

编辑现有图片：

bash

uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "让天空更有氛围感，添加乌云" --filename "2025-11-23-14-25-30-dramatic-sky.png" --input-image "original-photo.jpg" --resolution 2K