Nano Banana - Gemini Image Generation

Generate and edit images from text prompts via Google's Gemini image generation API.

When to Use

• User requests image generation, creation, or production from a text description
• Editing existing images with text instructions
• Style-transfer: generate new images that match the aesthetic of a reference
• Creating illustrations for presentations, articles, thumbnails, social posts
• Batch variations of the same concept

First-Time Setup

scripts/nano_banana.py init

Wizard checks dependencies (sops, age, magick), verifies the API key, and saves defaults to ~/.config/nano-banana/config.yaml.

Quick Start

# Simple generation
scripts/nano_banana.py "a minimalist illustration of a rocket" ./rocket.png

# With style preset
scripts/nano_banana.py --preset editorial "interconnected nodes" ./nodes.png

# YouTube thumbnail (auto-cropped to 1280x720)
scripts/nano_banana.py --preset grain --platform youtube "coffee on desk" ./thumb.png

# Generate 4 variants + contact sheet
scripts/nano_banana.py --preset wireframe "a crystal" ./crystal.png --n 4

# Edit existing image
scripts/nano_banana.py --edit ./old.png "make the background deep teal" ./new.png

# Style reference (match aesthetic of existing image)
scripts/nano_banana.py --reference ./style.png "a new mountain landscape" ./mountain.png

# Re-roll last prompt
scripts/nano_banana.py again

# View history
scripts/nano_banana.py history -n 10

Requirements

• GEMINI_API_KEY — auto-decrypted from secrets.enc.yaml via SOPS + age. Fallback: export GEMINI_API_KEY=...
• sops, age — for key decryption
• magick (ImageMagick) — for platform fit + contact sheets
• python3 with pyyaml

Models

Use via --model flash|pro|flash-2.5 or full ID.

Style Presets

scripts/nano_banana.py list-presets
scripts/nano_banana.py --preset editorial "your subject" out.png

Defined in presets.yaml — edit to add your own.

Platform Presets

scripts/nano_banana.py list-platforms
scripts/nano_banana.py --platform youtube "your subject" out.png

Generated image is automatically resized + center-cropped to target dimensions.

Features

Variants + Contact Sheet

--n N generates N variants in parallel and assembles them into a contact sheet:

scripts/nano_banana.py --preset ink "mountain" ./mt.png --n 6
# Creates mt-01.png ... mt-06.png + mt-contact.png

Batch generation (campaigns / multi-copy ad sets)

When each output needs different text or a different prompt (e.g. a set of ads sharing one style), loop over a list. --n won't help here — it re-rolls the same prompt. Use a shared $STYLE string + a per-item array.

cd /abs/output/dir
REF="_reference.png"   # optional style anchor
STYLE="<shared visual-style description, written once>"

# Each entry: pipe-delimited fields + output filename. NAME the array — see gotchas.
ADS=(
"CALL NOW|FOR TOTAL|CONFIDENTIALITY|ad-callnow.png"
"REDACT|BEFORE|YOU SEND|ad-redact.png"
)
for entry in "${ADS[@]}"; do
  IFS='|' read -r L1 L2 L3 OUT <<< "$entry"
  python3 scripts/nano_banana.py \
    "$STYLE The exact text reads, on three centered lines: '$L1' / '$L2' / '$L3'. Spell every word correctly." \
    "$OUT" --reference "$REF" --platform youtube --model pro --no-metadata --project NAME
done

Shell gotchas (this is zsh on macOS — these bite every time):

• Never name a loop array LINES, COLUMNS, PATH, path, status, argv, etc. — zsh reserves them. LINES=(...) fails with can't assign array value to non-array special. Use ADS, ITEMS, JOBS.
• zsh does NOT word-split unquoted variables (unlike bash). CMD="magick montage"; $CMD ... looks for a single command literally named "magick montage". Don't stuff multi-word commands in a var — call the command directly, or use an array (cmd=(magick montage); "${cmd[@]}").
• Always quote expansions — "$OUT", "${ADS[@]}" — paths and prompts contain spaces.
• Use 'single quotes' for the exact text you want rendered, inside the double-quoted prompt, so the model reproduces it verbatim.
• To parallelize a batch, append & per iteration and wait at the end — but cap concurrency (the API rate-limits); sequential is safest for >6 items.

After a batch, assemble a review sheet by calling the tool directly (no var indirection): magick montage ad-*.png -tile 2x3 -geometry 480x270+6+6 -background black _contact.png.

Edit Mode

Pass an existing image and the prompt becomes the edit instruction:

scripts/nano_banana.py --edit ./thumb.png "remove the watermark, warmer colors" ./clean.png

Reference Images (Style Anchor)

Use one or more reference images to guide the aesthetic without editing them:

scripts/nano_banana.py --reference ./episode1.png --reference ./episode2.png \
  "episode 3: data drift" ./ep3.png

Projects + Metadata

Organize outputs by project:

scripts/nano_banana.py --project lab-04/meeting-02 --preset editorial "MCP loops" ./overlay.png
# Saves to ~/nano-banana/outputs/lab-04/meeting-02/20260414-<subject>.png + .json sidecar

Re-roll + History

scripts/nano_banana.py again              # rerun last prompt
scripts/nano_banana.py history -n 20      # show last 20 generations
scripts/nano_banana.py history --project lab-04

Dry Run

Preview the composed prompt without calling the API:

scripts/nano_banana.py --preset editorial --platform youtube "subject" --dry-run

Transient Errors & Retry

The API occasionally returns 500/INTERNAL or empty candidates. The script retries up to 4 times with exponential backoff (2s, 4s, 8s, 16s). Permanent errors (4xx, safety violations) fail fast without retry.

Prompt Tips

• Specify visual style: "photograph", "flat illustration", "watercolor", "3D render"
• Include composition: "centered", "white background", "wide shot"
• Name colors: "blue and white color scheme", "warm earth tones"
• For text rendering, use --model pro and quote exact text: 'with the text "Hello"'

See references/api_reference.md for full API documentation.

Files

• scripts/nano_banana.py — main CLI (Python)
• scripts/generate_image.sh — thin bash wrapper (back-compat)
• presets.yaml — style presets
• platforms.yaml — platform sizing presets
• secrets.enc.yaml — encrypted API key (SOPS + age)
• ~/.config/nano-banana/config.yaml — user defaults (from init)
• ~/.config/nano-banana/history.jsonl — generation log
• ~/.config/nano-banana/last.json — last run (for again)