介绍
# Nano Banana Pro Image Generation & Editing
使用 Google Nano Banana Pro API (Gemini 3 Pro Image) 生成新图像或编辑现有图像。
## 用法
使用绝对路径运行脚本（请**不要**先 cd 到技能目录）：
**生成新图像：** ```bash 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] ```
**编辑现有图像：** ```bash 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] ```
**重要：** 始终从用户的当前工作目录运行，以便图像保存在用户工作的地方，而不是技能目录中。
## 默认工作流程 (draft → iterate → final)
目标：在不提示词正确之前，不在 4K 分辨率上浪费时间，实现快速迭代。
- Draft (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` - Iterate：通过微小的差异调整提示词；每次运行保持文件名唯一 - 如果是编辑：直到您满意之前，每次迭代都保持相同的 `--input-image`。 - Final (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 Pro Image API 支持三种分辨率（必须大写 K）：
- **1K** (默认) - ~1024px 分辨率 - **2K** - ~2048px 分辨率 - **4K** - ~4096px 分辨率
将用户请求映射到 API 参数： - 未提及分辨率 → `1K` - "low resolution", "1080", "1080p", "1K" → `1K` - "2K", "2048", "normal", "medium resolution" → `2K` - "high resolution", "high-res", "hi-res", "4K", "ultra" → `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` - Timestamp：当前日期/时间，格式为 `yyyy-mm-dd-hh-mm-ss`（24 小时制） - Name：描述性的小写文本，使用连字符 - 保持描述部分简洁（通常 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` 中传递编辑指令（例如，“在天空中添加彩虹”，“让它看起来像水彩画”）
在两种情况下都要保留用户的创作意图。
## 提示词模板 (高命中率)
当用户描述模糊或编辑必须精确时，请使用模板。
- 生成模板： - “Create an image of: <subject>. Style: <style>. Composition: <camera/shot>. Lighting: <lighting>. Background: <background>. Color palette: <palette>. Avoid: <list>.”
- 编辑模板（保留其他所有内容）： - “Change ONLY: <single change>. 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.”
## 输出
- 将 PNG 保存到当前目录（如果文件名包含目录，则保存到指定路径） - 脚本输出生成图像的完整路径 - **不要读回图像** - 只需告知用户保存的路径
## 示例
**生成新图像：** ```bash 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 ```
**编辑现有图像：** ```bash 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 ```