nano-banana-pro

Nano Banana 2 图像生成与编辑

使用 Google 的 Nano Banana 2 API（Gemini 3.1 Flash Image）生成新图像或编辑现有图像。

用法

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

生成新图像：

uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "your image description" --filename "output-name.png" [--resolution 512|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 512|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
• 迭代：小幅调整提示词；每次运行都使用新的文件名
  • 如果是编辑图像：在每次迭代中都使用相同的 --input-image，直到满意为止。
• 最终版（4K）：仅在提示词确定后生成
  • 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

分辨率选项

Gemini 3.1 Flash Image API 支持以下输出尺寸值：

• 512 - 紧凑型约 512px 级别的分辨率
• 1K（默认）- 约 1024px 分辨率
• 2K - 约 2048px 分辨率
• 4K - 约 4096px 分辨率

将用户请求映射为 API 参数：

• “512”、“512px”、“0.5K”、“缩略图”、“极小” → 512
• 未提及分辨率 → 1K
• “低分辨率”、“1080”、“1080p”、“1K” → 1K
• “2K”、“2048”、“普通”、“中等分辨率” → 2K
• “高分辨率”、“高分辨率图像”、“高清”、“4K”、“超高” → 4K

API 密钥

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

1. --api-key 参数（用户在聊天中提供密钥时使用）
2. GEMINI_API_KEY 环境变量

如果两者都不可用，脚本会退出并显示错误消息。

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

• 预检：

  • 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 指向真实图像
  • “quota/permission/403” 类型的 API 错误 → 密钥错误、无访问权限或配额已超限；请尝试其他密钥或账户

文件名生成

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

格式：{timestamp}-{descriptive-name}.png

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

示例：

• 提示词“宁静的日式花园” → 2025-11-23-14-23-05-japanese-garden.png
• 提示词“山间日落” → 2025-11-23-15-30-12-sunset-mountains.png
• 提示词“创建一张机器人的图像” → 2025-11-23-16-45-33-robot.png
• 上下文不明确 → 2025-11-23-17-12-48-x9k2.png

图像编辑

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

1. 检查用户是否提供了图像路径，或是否提到了当前目录中的图像
2. 使用 --input-image 参数指定图像路径
3. 提示词应包含编辑说明（例如，“让天空更具戏剧感”、“移除人物”、“改成卡通风格”）
4. 常见编辑任务：添加/移除元素、更改风格、调整颜色、模糊背景等

提示词处理

**生成图像：**将用户的图像描述原样传给 --prompt。只有在内容明显不足时才进行改写。

**编辑图像：**将编辑说明传给 --prompt（例如，“在天空中添加一道彩虹”、“让它看起来像水彩画”）。

无论哪种情况，都要保留用户的创作意图。

提示词模板（命中率高）

当用户表达模糊或需要精确编辑时，使用模板。

• 生成模板：

  • “创建一张图像：。风格：。构图：<camera/shot>。光线：<lighting>。背景：<background>。调色板：<palette>。避免：<list>。”

• 编辑模板（保留其他所有内容）：

  • “仅更改：。保持以下内容完全一致：主体、构图/裁切、姿势、光线、调色板、背景、文字和整体风格。不要添加新对象。如果有文字，保持不变。”

输出

• 将 PNG 保存到当前目录（如果文件名包含目录，则保存到指定路径）
• 必须使用新文件名：若文件已存在，或目标是硬链接、符号链接，则会拒绝写入。必要时会创建父目录，但不允许路径组件是符号链接；请改用其真实目录路径。在 macOS 和 Linux 上，仍支持绝对路径及当前目录之外的路径。
• 脚本会输出生成图像的完整路径
• 不要读取图像——只需告知用户保存路径

离线输出安全回归测试（需要 Pillow）：从仓库根目录运行 python3 -m unittest discover -s skills/nano-banana-pro/scripts -p 'test_*.py'。

示例

生成新图像：

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