/nanobanana

name: nanobanana
description: AI image generation and editing using Google Gemini models. Use when the user asks to generate an image, create an image, edit an image, or mentions "nano banana", "nanobanana", "gemini image", "AI image", "generate a picture", or needs any image created or modified.

Nano Banana - AI Image Generation

Generate and edit images using Google Gemini models. Supports two models:

• **Pro** (`gemini-3-pro-image-preview`) — High quality, complex prompts, thinking mode
• **Flash** (`gemini-2.5-flash-image`) — Fast, cheap, good for iteration

Prerequisites

**Required:**

• `GEMINI_API_KEY` — Get from [Google AI Studio](https://aistudio.google.com/apikey)
• [`uv`](https://docs.astral.sh/uv/) (recommended) or Python 3.10+ with `google-genai` installed

**With `uv` (recommended — zero setup):** Dependencies are declared inline via PEP 723 and auto-installed on first run. Just use `uv run` instead of `python3`.

**With pip (fallback):**

pip install -r ${CLAUDE_SKILL_DIR}/requirements.txt

Quick Start

**Default output:** Images save to `~/Downloads/nanobanana_<timestamp>.png` automatically. Do NOT pass `-o` unless the user specifies where to save. If the user provides a filename without a directory (e.g., "save it as robot.png"), use `-o ~/Downloads/robot.png`.

Generate an image:

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "a cute robot mascot, pixel art style"

Edit an existing image:

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "make the background blue" -i input.jpg

Use Flash model for fast iteration:

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "quick sketch of a cat" --model flash

Multi-image reference (style + subject):

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "apply the style of the first image to the second" \
  -i style_ref.png subject.jpg

Generate with specific aspect ratio and resolution:

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "cinematic landscape" --ratio 21:9 --size 4K

Save to a specific location:

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "logo design" -o ~/Projects/brand/logo.png

Model Selection Guide

| | Pro (default) | Flash | |---|---|---| | **Speed** | Slower | ~2-3x faster | | **Cost** | Higher | Lower | | **Text rendering** | Good | Unreliable | | **Complex scenes** | Excellent | Adequate | | **Thinking mode** | Yes | No | | **Best for** | Final production images | Exploration, drafts, batch |

**Rule of thumb:** Use Flash for exploration and batch generation, Pro for final output.

Script Reference

`scripts/generate.py`

Main image generation script.

Usage: generate.py [OPTIONS] PROMPT

Arguments:
  PROMPT                Text prompt for image generation

Options:
  -o, --output PATH     Output file path (default: ~/Downloads/nanobanana_<timestamp>.png)
  -i, --input PATH...   Input image(s) for editing / reference (up to 14)
  -m, --model MODEL     Model: 'pro' (default), 'flash', or full model ID
  -r, --ratio RATIO     Aspect ratio (1:1, 16:9, 9:16, 21:9, etc.)
  -s, --size SIZE       Image size: 1K, 2K, or 4K (default: standard)
  --search              Enable Google Search grounding for accuracy
  --retries N           Max retries on rate limit (default: 3)
  -v, --verbose         Show detailed output

**Supported aspect ratios:**

• `1:1` — Square (default)
• `2:3`, `3:2` — Portrait/Landscape
• `3:4`, `4:3` — Standard
• `4:5`, `5:4` — Photo
• `9:16`, `16:9` — Widescreen
• `21:9` — Ultra-wide/Cinematic

**Image sizes:**

• `1K` — Fast, lower detail
• `2K` — Enhanced detail (2048px)
• `4K` — Maximum quality (3840px), best for text rendering

`scripts/batch_generate.py`

Generate multiple images with sequential naming.

Usage: batch_generate.py [OPTIONS] PROMPT

Arguments:
  PROMPT                Text prompt for image generation

Options:
  -n, --count N         Number of images to generate (default: 10)
  -d, --dir PATH        Output directory (default: ~/Downloads)
  -p, --prefix STR      Filename prefix (default: "image")
  -m, --model MODEL     Model: 'pro' (default), 'flash', or full model ID
  -r, --ratio RATIO     Aspect ratio
  -s, --size SIZE       Image size (1K/2K/4K)
  --search              Enable Google Search grounding
  --retries N           Max retries per image on rate limit (default: 3)
  --delay SECONDS       Delay between generations (default: 3)
  --parallel N          Concurrent requests (default: 1, max recommended: 5)
  -q, --quiet           Suppress progress output

**Example:**

uv run ${CLAUDE_SKILL_DIR}/scripts/batch_generate.py "pixel art logo" -n 20 --model flash -d ./logos -p logo

Python API

Direct import (from another skill's script):

> **Note:** When importing as a Python module, `google-genai` must be available in the calling script's environment. If using `uv run`, add a PEP 723 `dependencies` block to your own script (see example in Pattern 2 below).

import sys
from pathlib import Path
sys.path.insert(0, str(Path("${CLAUDE_SKILL_DIR}/scripts")))
from generate import generate_image, edit_image, batch_generate

# Generate image
result = generate_image(
    prompt="a futuristic city at night",
    output_path="city.png",
    aspect_ratio="16:9",
    image_size="4K",
    model="pro",
)

# Edit existing image
result = edit_image(
    prompt="add flying cars to the sky",
    input_path="city.png",
    output_path="city_edited.png",
)

# Multi-image reference
result = generate_image(
    prompt="combine the color palette of the first with the composition of the second",
    input_paths=["palette_ref.png", "composition_ref.png"],
    output_path="combined.png",
)

Return structure (always present):

{
    "success": True,       # or False
    "path": "/path/to/output.png",  # or None on failure
    "error": None,         # or error message string
    "metadata": {
        "model": "gemini-