Nano Banana Pro Image Generation & Editing

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

Usage

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

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. 目标：快速迭代，直到提示词正确之前，不要在4K上浪费时间。

• 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
  • 草稿(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.
  • 迭代：小幅调整提示词；每次运行使用新的文件名
  • 如果是编辑：在每次迭代中保持相同的--input-image，直到您满意为止。

• 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
  • 最终版(4K)：仅在提示词确定后使用

Resolution Options

The Gemini 3 Pro Image API supports three resolutions (uppercase K required): Gemini 3 Pro Image API支持三种分辨率（需要大写的K）：

• 1K (default) - ~1024px resolution

  • 1K（默认）- 约1024px分辨率

• 2K - ~2048px resolution

  • 2K - 约2048px分辨率

• 4K - ~4096px resolution

  • 4K - 约4096px分辨率

Map user requests to API parameters: 将用户请求映射到API参数：

• No mention of resolution → 1K

  • 未提及分辨率 → 1K

• "low resolution", "1080", "1080p", "1K" → 1K

  • "低分辨率", "1080", "1080p", "1K" → 1K

• "2K", "2048", "normal", "medium resolution" → 2K

  • "2K", "2048", "普通", "中等分辨率" → 2K

• "high resolution", "high-res", "hi-res", "4K", "ultra" → 4K

  • "高分辨率", "高分辨率", "高分辨率", "4K", "超高清" → 4K

API Key

The script checks for API key in this order: 脚本按以下顺序检查API密钥：

1. --api-key argument (use if user provided key in chat)

   • --api-key 参数（如果用户在聊天中提供了密钥）

2. GEMINI_API_KEY environment variable

   • GEMINI_API_KEY 环境变量

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\"

  • 预检查：

    • command -v uv（必须存在）
    • test -n \"$GEMINI_API_KEY\"（或传递--api-key）
    • 如果是编辑：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

  • 常见故障：

    • 错误：未提供API密钥。 → 设置GEMINI_API_KEY或传递--api-key
    • 加载输入图像错误： → 路径错误/文件无法读取；验证--input-image指向真实图像
    • "配额/权限/403"类型的API错误 → 密钥错误、无访问权限或配额已用完；尝试使用不同的密钥/账户

Filename Generation

Generate filenames with the pattern: yyyy-mm-dd-hh-mm-ss-name.png 使用以下模式生成文件名：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

图像编辑

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

1. 检查他们是否提供了图像路径或引用了当前目录中的图像
2. 使用带有图像路径的 --input-image 参数
3. 提示应包含编辑说明（例如，"让天空更戏剧化"，"移除人物"，"改为卡通风格"）
4. 常见编辑任务：添加/删除元素，更改风格，调整颜色，模糊背景等

提示处理

用于生成： 将用户的图像描述原样传递给 --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