Nano Banana Pro：基于Gemini 3 Pro的AI图像生成与编辑工具，支持1K/2K/4K分辨率

nano-banana-pro by steipete/agent-scripts

107 周安装量

2,300 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/steipete/agent-scripts --skill nano-banana-pro

AI/机器学习图像处理命令行工具

🇨🇳中文介绍

Nano Banana Pro 图像生成与编辑

使用 Google 的 Nano Banana Pro API (Gemini 3 Pro Image) 生成新图像或编辑现有图像。

使用方法

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

生成新图像：

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]

编辑现有图像：

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]

重要提示： 始终从用户的当前工作目录运行，以便图像保存在用户工作的地方，而不是技能目录中。

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

目标：快速迭代，在提示词确定之前不浪费时间在 4K 分辨率上。

草稿 (1K)：快速反馈循环
- 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

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

预检 + 常见故障（快速修复）

预检：
- command -v uv (必须存在)
- test -n \"$GEMINI_API_KEY\" (或传递 --api-key)
- 如果正在编辑：test -f \"path/to/input.png\"
常见故障：
- Error: No API key provided. → 设置 GEMINI_API_KEY 或传递 --api-key
- Error loading input image: → 路径错误 / 文件不可读；验证 --input-image 指向真实的图像文件
- “配额/权限/403” 类型的 API 错误 → 密钥错误、无访问权限或配额已用尽；尝试不同的密钥/账户

使用以下模式生成文件名：yyyy-mm-dd-hh-mm-ss-name.png

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

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

提示 "A serene Japanese garden" → 2025-11-23-14-23-05-japanese-garden.png
提示 "sunset over mountains" → 2025-11-23-15-30-12-sunset-mountains.png
提示 "create an image of a robot" → 2025-11-23-16-45-33-robot.png
上下文不明确 → 2025-11-23-17-12-48-x9k2.png

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

检查他们是否提供了图像路径或引用了当前目录中的图像
使用 --input-image 参数并指定图像路径
提示词应包含编辑指令（例如，"让天空更具戏剧性", "移除人物", "改为卡通风格"）
常见编辑任务：添加/移除元素、更改风格、调整颜色、模糊背景等。

对于生成： 将用户的图像描述原样传递给 --prompt。仅在明显不足时进行改写。

对于编辑： 在 --prompt 中传递编辑指令（例如，"在天空中添加一道彩虹", "使其看起来像水彩画"）

在两种情况下都要保留用户的创作意图。

提示词模板（高成功率）

当用户描述模糊或编辑需要精确时使用模板。

生成模板：
- “创建一张图像：。风格：。构图：<相机/镜头>。光照：。背景：。色彩搭配：。避免：。”
编辑模板（保留其他所有内容）：
- “仅更改：。保持完全相同：主体、构图/裁剪、姿势、光照、色彩搭配、背景、文本和整体风格。不要添加新对象。如果存在文本，保持其不变。”

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

生成新图像：

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

编辑现有图像：

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

🇺🇸English

Nano Banana Pro Image Generation & Editing

Generate new images or edit existing ones using Google's 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:

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:

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.

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

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

API Key

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.

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

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

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.

Prompt Handling

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 Templates (high hit-rate)

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

Generation template:
- “Create an image of: . Style: . Composition: <camera/shot>. Lighting: . Background: . Color palette: . Avoid: .”
Editing template (preserve everything else):
- “Change ONLY: . 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

Examples

Generate new image:

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:

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

Weekly Installs

107

Repository

steipete/agent-scripts

GitHub Stars

2.3K

First Seen

Jan 23, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykFail

Installed on

codex95

opencode94

gemini-cli89

cursor84

github-copilot82

claude-code69

AI 代码实施计划编写技能 | 自动化开发任务分解与 TDD 流程规划工具

48,300 周安装

“quota/permission/403” style API errors → wrong key, no access, or quota exceeded; try a different key/account