nano-banana

name	nano-banana
description	Generate and edit images using Google's Gemini image generation models (Nano Banana family). Supports style presets, platform-specific sizing (YouTube/slides/blog), variants, image editing via inlineData, reference images for style transfer, and organized output with metadata. Default model is Nano Banana 2 (gemini-3.1-flash-image-preview). Key is auto-decrypted via SOPS.

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

Model	Alias	Nano Banana Name	Use When
gemini-3.1-flash-image-preview (default)	flash	Nano Banana 2	Best instruction following, fast
gemini-3-pro-image-preview	pro	Nano Banana Pro	Highest quality, text in images
gemini-2.5-flash-image	flash-2.5	Nano Banana (original)	Legacy

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

Preset	Style
editorial	Thin lines on black, muted palette, technical diagram feel
blueprint	White/cyan lines on dark navy, engineering drawing
ink	Japanese sumi-e ink wash, organic brushstrokes, monochrome
risograph	Flat colors, grain, terracotta + sage, zine aesthetic
wireframe	3D wireframe mesh, glowing edges on black
constellation	Star map dots connected by faint lines, celestial
brutalist	Bold shapes, thick borders, hard shadows, flat colors
grain	Film grain photo, high ISO, warm cinematic tones

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.

Platform	Size
youtube	1280×720
youtube-short	1080×1920
slides	1920×1080
blog	1200×630
x	1600×900
square	1080×1080
story	1080×1920
pinterest	1000×1500

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)