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 "你的图像描述" --filename "输出文件名.png" [--resolution 512|1K|2K|4K] [--api-key KEY]
编辑现有图像:
uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "编辑说明" --filename "输出文件名.png" --input-image "输入图像路径.png" [--resolution 512|1K|2K|4K] [--api-key KEY]
重要: 始终从用户的当前工作目录运行,以便图像保存到用户工作目录,而不是技能目录。
默认工作流(草稿 → 迭代 → 最终)
目标:快速迭代,在提示词确认正确之前不浪费 4K 时间。
- 草稿(1K):快速反馈循环
uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "<草稿提示>" --filename "yyyy-mm-dd-hh-mm-ss-草稿.png" --resolution 1K
- 迭代:逐步调整提示词;每次运行保持文件名新
- 如果是编辑模式:在对结果满意之前,每次迭代都保持相同的
--input-image。
- 如果是编辑模式:在对结果满意之前,每次迭代都保持相同的
- 最终(4K):仅在提示词确定后使用
uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "<最终提示>" --filename "yyyy-mm-dd-hh-mm-ss-最终.png" --resolution 4K
分辨率选项
Gemini 3.1 Flash Image API 支持以下输出尺寸:
- 512 - 紧凑型 ~512px 类分辨率
- 1K(默认)- ~1024px 分辨率
- 2K - ~2048px 分辨率
- 4K - ~4096px 分辨率
将用户请求映射到 API 参数:
- "512", "512px", "0.5K", "thumbnail", "tiny" →
512 - 未提及分辨率 →
1K - "low resolution", "1080", "1080p", "1K" →
1K - "2K", "2048", "normal", "medium resolution" →
2K - "high resolution", "high-res", "hi-res", "4K", "ultra" →
4K
API 密钥
脚本按以下顺序检查 API 密钥:
--api-key参数(如果用户在聊天中提供了密钥则使用)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-keyError loading input image:→ 路径错误/文件不可读;验证--input-image指向一个真实的图像文件- “quota/permission/403” 风格的 API 错误 → 密钥错误、无访问权限或配额超限;尝试其他密钥/账户
文件名生成
使用以下模式生成文件名:yyyy-mm-dd-hh-mm-ss-名称.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