Nano Banana Pro 图像生成与编辑

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

使用方法

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

生成新图像：

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

编辑现有图像：

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

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

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

目标：快速迭代，在提示词正确之前不要浪费时间生成 4K 图像。

• 草稿 (1K)：快速反馈循环
  • uv run ~/.codex/skills/nano-banana-pro-zh/scripts/generate_image.py --prompt "<草稿提示词>" --filename "yyyy-mm-dd-hh-mm-ss-draft.png" --resolution 1K
• 迭代：以小幅差异调整提示词；每次运行保持文件名更新
  • 如果是编辑：每次迭代使用相同的 --input-image 直到满意为止
• 最终 (4K)：仅在提示词确定后使用
  • uv run ~/.codex/skills/nano-banana-pro-zh/scripts/generate_image.py --prompt "<最终提示词>" --filename "yyyy-mm-dd-hh-mm-ss-final.png" --resolution 4K

分辨率选项

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

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

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

• 未提及分辨率 → 1K
• "低分辨率"、"1080"、"1080p"、"1K" → 1K
• "2K"、"2048"、"普通"、"中等分辨率" → 2K
• "高分辨率"、"高清"、"hi-res"、"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"

• 常见故障：

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

文件名生成

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

格式： {时间戳}-{描述性名称}.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 中传递编辑指令（例如 "在天空中添加彩虹"、"让它看起来像水彩画"）

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

提示词模板（高成功率）

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

• 生成模板：

  • "创建图像：<主体>。风格：<风格>。构图：<镜头/拍摄>。光线：<光线>。背景：<背景>。调色板：<调色板>。避免：<列表>。"

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

  • "仅更改：<单个更改>。完全保持：主体、构图/裁剪、姿势、光线、调色板、背景、文本和整体风格。不要添加新对象。如果存在文本，保持不变。"

输出

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

示例

生成新图像：

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

编辑现有图像：

uv run ~/.codex/skills/nano-banana-pro-zh/scripts/generate_image.py --prompt "让天空更具戏剧性，添加暴风云" --filename "2025-11-23-14-25-30-dramatic-sky.png" --input-image "original-photo.jpg" --resolution 2K