Back to Details

nano-banana-pro

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Nano Banana Pro Image Generation & Editing

Nano Banana Pro 图片生成与编辑

Generate new images or edit existing ones using Google's Nano Banana Pro API (Gemini 3 Pro Image).
使用Google的Nano Banana Pro API（Gemini 3 Pro Image）生成新图片或编辑现有图片。

Usage

使用方法

Run the script using absolute path (do NOT cd to skill directory first):
Generate new image:
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]
Edit existing image:
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]
Important: Always run from the user's current working directory so images are saved where the user is working, not in the skill directory.
请使用绝对路径运行脚本（不要先切换到技能目录）：
生成新图片：
bash
uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "你的图片描述" --filename "输出名称.png" [--resolution 1K|2K|4K] [--api-key KEY]
编辑现有图片：
bash
uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "编辑指令" --filename "输出名称.png" --input-image "输入图片路径.png" [--resolution 1K|2K|4K] [--api-key KEY]
重要提示： 始终从用户当前工作目录运行脚本，这样图片会保存到用户的工作目录，而非技能目录。

Default Workflow (draft → iterate → final)

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

Goal: fast iteration without burning time on 4K until the prompt is correct.
  • 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
  • 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.
  • 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
目标：快速迭代，在确定prompt合适之前，不要浪费时间生成4K图片。
  • 草稿（1K）：快速反馈循环 
    • uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "<草稿prompt>" --filename "yyyy-mm-dd-hh-mm-ss-draft.png" --resolution 1K
  • 迭代：小幅调整prompt；每次运行使用新的文件名
    • 如果是编辑操作：在满意之前，每次迭代都使用相同的
      --input-image
  • 最终版本（4K）：仅当prompt确定后使用 
    • uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "<最终prompt>" --filename "yyyy-mm-dd-hh-mm-ss-final.png" --resolution 4K

Resolution Options

分辨率选项

The Gemini 3 Pro Image API supports three resolutions (uppercase K required):
  • 1K (default) - ~1024px resolution
  • 2K - ~2048px resolution
  • 4K - ~4096px resolution
Map user requests to API parameters:
  • No mention of resolution → 
    1K
  • "low resolution", "1080", "1080p", "1K" → 
    1K
  • "2K", "2048", "normal", "medium resolution" → 
    2K
  • "high resolution", "high-res", "hi-res", "4K", "ultra" → 
    4K
Gemini 3 Pro Image API支持三种分辨率（K必须大写）：
  • 1K（默认）- 约1024px分辨率
  • 2K - 约2048px分辨率
  • 4K - 约4096px分辨率
用户请求与API参数的映射：
  • 未提及分辨率 → 
    1K
  • "低分辨率", "1080", "1080p", "1K" → 
    1K
  • "2K", "2048", "普通", "中等分辨率" → 
    2K
  • "高分辨率", "high-res", "hi-res", "4K", "ultra" → 
    4K

API Key

API密钥

The script checks for API key in this order:
  1. --api-key
    argument (use if user provided key in chat)
  2. GEMINI_API_KEY
    environment variable
If neither is available, the script exits with an error message.
脚本会按以下顺序查找API密钥：
  1. --api-key
    参数（如果用户在对话中提供了密钥）
  2. GEMINI_API_KEY
    环境变量
如果两者都不存在，脚本会退出并显示错误信息。

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\"
  • 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
  • 预检：
    • command -v uv
      （必须存在）
    • test -n \"$GEMINI_API_KEY\"
      （或传入
      --api-key
      ）
    • 如果是编辑操作：
      test -f \"输入图片路径.png\"
  • 常见错误：
    • Error: No API key provided.
      → 设置
      GEMINI_API_KEY
      环境变量或传入
      --api-key
      参数
    • Error loading input image:
      → 路径错误或文件不可读；确认
      --input-image
      指向真实存在的图片
    • “quota/permission/403”类API错误 → 密钥错误、无访问权限或配额用尽；尝试更换密钥/账号

Filename Generation

文件名生成

Generate filenames with the pattern: 
yyyy-mm-dd-hh-mm-ss-name.png
Format: 
{timestamp}-{descriptive-name}.png
  • Timestamp: Current date/time in format 
    yyyy-mm-dd-hh-mm-ss
    (24-hour format)
  • Name: Descriptive lowercase text with hyphens
  • Keep the descriptive part concise (1-5 words typically)
  • Use context from user's prompt or conversation
  • If unclear, use random identifier (e.g., 
    x9k2
    , 
    a7b3
    )
Examples:
  • Prompt "A serene Japanese garden" → 
    2025-11-23-14-23-05-japanese-garden.png
  • Prompt "sunset over mountains" → 
    2025-11-23-15-30-12-sunset-mountains.png
  • Prompt "create an image of a robot" → 
    2025-11-23-16-45-33-robot.png
  • Unclear context → 
    2025-11-23-17-12-48-x9k2.png
使用以下格式生成文件名：
yyyy-mm-dd-hh-mm-ss-name.png
格式： 
{时间戳}-{描述性名称}.png
  • 时间戳：当前日期/时间，格式为
    yyyy-mm-dd-hh-mm-ss
    （24小时制）
  • 名称：简洁的小写描述性文本，用连字符分隔
  • 描述部分保持简洁（通常1-5个词）
  • 使用用户prompt或对话中的上下文信息
  • 如果上下文不明确，使用随机标识符（例如
    x9k2
    , 
    a7b3
    ）
示例：
  • Prompt "宁静的日式花园" → 
    2025-11-23-14-23-05-japanese-garden.png
  • Prompt "山间日落" → 
    2025-11-23-15-30-12-sunset-mountains.png
  • Prompt "创建一张机器人的图片" → 
    2025-11-23-16-45-33-robot.png
  • 上下文不明确 → 
    2025-11-23-17-12-48-x9k2.png

Image Editing

图片编辑

When the user wants to modify an existing image:
  1. Check if they provide an image path or reference an image in the current directory
  2. Use 
    --input-image
    parameter with the path to the image
  3. The prompt should contain editing instructions (e.g., "make the sky more dramatic", "remove the person", "change to cartoon style")
  4. Common editing tasks: add/remove elements, change style, adjust colors, blur background, etc.
当用户想要修改现有图片时：
  1. 检查用户是否提供了图片路径或引用了当前目录中的图片
  2. 使用
    --input-image
    参数传入图片路径
  3. Prompt中应包含编辑指令（例如"让天空更有氛围感", "移除人物", "改为卡通风格"）
  4. 常见编辑任务：添加/移除元素、更改风格、调整颜色、模糊背景等

Prompt Handling

Prompt处理

For generation: Pass user's image description as-is to 
--prompt
. Only rework if clearly insufficient.
For editing: Pass editing instructions in 
--prompt
(e.g., "add a rainbow in the sky", "make it look like a watercolor painting")
Preserve user's creative intent in both cases.
生成图片： 将用户的图片描述直接传入
--prompt
。仅当描述明显不充分时才进行修改。
编辑图片： 将编辑指令传入
--prompt
（例如"在天空中添加彩虹", "让它看起来像水彩画"） 在两种情况下都要保留用户的创意意图。

Prompt Templates (high hit-rate)

高成功率Prompt模板

Use templates when the user is vague or when edits must be precise.
  • Generation template:
    • “Create an image of: <subject>. Style: <style>. Composition: <camera/shot>. Lighting: <lighting>. Background: <background>. Color palette: <palette>. Avoid: <list>.”
  • Editing template (preserve everything else):
    • “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.”
当用户的需求模糊或编辑需要精准时，使用以下模板。
  • 生成模板：
    • “创建一张图片：<主体>。风格：<风格>。构图：<镜头/视角>。光线：<光线效果>。背景：<背景>。调色板：<调色板>。避免：<列表>。”
  • 编辑模板（保留其他所有元素）：
    • “仅修改：<单一修改内容>。保持以下元素完全不变：主体、构图/裁剪、姿势、光线、调色板、背景、文字和整体风格。不要添加新物体。如果存在文字，保持其不变。”

Output

输出

  • Saves PNG to current directory (or specified path if filename includes directory)
  • Script outputs the full path to the generated image
  • Do not read the image back - just inform the user of the saved path
  • 将PNG图片保存到当前目录（如果文件名包含目录，则保存到指定路径）
  • 脚本会输出生成图片的完整路径
  • 不要读取图片内容 - 只需告知用户保存路径即可

Examples

示例

Generate new image:
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
Edit existing image:
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
生成新图片：
bash
uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "宁静的日式花园，开满樱花" --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 "让天空更有氛围感，添加乌云" --filename "2025-11-23-14-25-30-dramatic-sky.png" --input-image "original-photo.jpg" --resolution 2K