notque/nano-banana-builder

Nano Banana Builder

Image generation and post-processing via two deterministic Python scripts (nano-banana-generate.py and nano-banana-process.py). Your job is prompt crafting and flag selection; the scripts handle all mechanical operations.

Instructions

1. Validate the environment

Before any generation call, confirm the API key is set. The scripts read GEMINI_API_KEY (or GOOGLE_API_KEY) from the environment and will fail without it. Checking this first avoids wasted time on API calls that will error immediately.

2. Choose the right script and subcommand

Translate user intent into the correct script call. Always call the scripts — never write inline PIL/sharp/image-processing code, because that duplicates tested logic and bypasses the deterministic pipeline.

| User wants | Script + subcommand | Key flags | |------------|-------------------|-----------| | Generate a single image | nano-banana-generate.py generate | --prompt, --model, --aspect-ratio | | Generate a sprite/character | nano-banana-generate.py generate | --model pro, --aspect-ratio 1:1 | | Generate card art | nano-banana-generate.py generate | --model flash, --aspect-ratio 16:9 | | Generate backgrounds | nano-banana-generate.py generate | --model flash, --aspect-ratio 9:16 (vertical) or 16:9 (landscape) | | Style-match a reference | nano-banana-generate.py with-reference | --reference, --prompt | | Batch generate enemies/items | nano-banana-generate.py batch | --manifest, --skip-existing, --delay 3 | | Crop to exact dimensions | nano-banana-process.py crop | --width, --height, --bias | | Make background transparent | nano-banana-process.py remove-bg | --bg-color, --tolerance | | Clean up watermarks | nano-banana-process.py remove-watermarks | --margin, --threshold | | Convert format | nano-banana-process.py convert | --format, --quality | | Full sprite pipeline | nano-banana-process.py pipeline | --remove-bg, --remove-watermarks, crop flags | | Batch reprocess originals | nano-banana-process.py pipeline | directory input, crop + format flags |

3. Select the model

Only two model aliases exist: flash (gemini-2.5-flash-image) and pro (gemini-3-pro-image-preview). The scripts enforce this — never pass raw Gemini model strings like gemini-2.5-flash-preview-05-20, because they don't support image generation and the call will fail. Use --model flash for drafts and iteration (fast, 2-5s). Use --model pro for final output (higher quality, ~30s).

4. Match aspect ratio to target shape

Set --aspect-ratio to match the final use so the generated image fills the frame. Generating 1:1 then cropping to 16:9 loses 56% of pixels and wastes quality. Valid ratios: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9.

• Sprites/characters: 1:1
• Card art: 16:9
• Vertical maps/backgrounds: 9:16
• Landscape arenas: 16:9

5. Save originals

For any batch or expensive generation, use --save-original (single) or --originals-dir (batch) to preserve raw API output before processing. Re-generating costs money and quota; re-processing a saved original is free. This enables experimentation with different crop/bg-removal settings without re-invoking the API.

6. Craft the prompt

Your unique contribution is writing effective prompts for the Gemini API.

Sprites/Characters (use with --model pro):

• Always specify: "solid dark gray background color only" (enables bg removal with --bg-color 3a3a3a)
• Always specify: "ONE character only, full body visible from head to feet, centered in frame"
• Always specify: "no text, no labels, no background details"
• Describe art style explicitly: "Slay the Spire card game style, heavy ink outlines, golden glowing outline"

Card Art (use with --model flash):

• Specify composition: "WIDE SHOT, full bodies with space around them"
• Specify style: "sketchy rough painterly, muted desaturated sepia palette"
• Include context: "wrestling ring ropes in background"

Backgrounds (use with --model flash):

• Specify darkness: "Very dark overall (UI elements need to be readable on top)"
• Specify no characters: "NO text, NO labels, NO characters"

7. Generate

Single image

python3 ~/.claude/scripts/nano-banana-generate.py generate \
    --prompt "PROMPT" \
    --output OUTPUT_PATH \
    --model flash|pro \
    --aspect-ratio RATIO \
    --save-original ORIGINAL_PATH

| Flag | Required | Default | Description | |------|----------|---------|-------------| | --prompt | Yes | -- | Text prompt for generation | | --output | Yes | -- | Output file path (.png or .jpg) | | --model | No | flash | flash (fast, 2-5s) or pro (quality, ~30s) | | --aspect-ratio | No | model default | 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 | | --reference | No | -- | Reference image for style matching | | --save-original | No | -- | Save raw API output to this path |

Style transfer (with-reference)

python3 ~/.claude/scripts/nano-banana-generate.py with-reference \
    --prompt "Recreate in this art style" \
    --reference style_ref.png \
    --output styled.png \
    --model flash --aspect-ratio 16:9

Same flags as generate but --reference is required.

Batch generation

Use --delay to stay within rate limits (default 2s for flash, 3s for pro). Use --skip-existing to avoid re-generating images that already exist.

python3 ~/.claude/scripts/nano-banana-generate.py batch \
    --manifest items.json \
    --output-dir staging/sprites/ \
    --originals-dir staging/originals/ \
    --model pro --aspect-ratio 1:1 \
    --skip-existing --variants 3 --delay 3

| Flag | Required | Default | Description | |------|----------|---------|-------------| | --manifest | Yes | -- | JSON file: [{"id": "name", "prompt": "...", "reference": "optional.png"}] | | --output-dir | Yes | -- | Directory for generated images | | --originals-dir | No | -- | Save raw API outputs here | | --skip-existing | No | off | Skip items with existing output files | | --variants | No | 1 | Number of variants per item (1-5) | | --delay | No | 2.0 | Seconds between API calls |

8. Post-process

Dependencies: pip install pillow (generation also needs pip install google-genai pillow).

Crop

Use --bias 0.35 when cropping character/sprite art to preserve heads (default 0.5 centers the crop).

python3 ~/.claude/scripts/nano-banana-process.py crop \
    --width 400 --height 218 --bias 0.35 \
    input.png output.png

| Flag | Required | Default | Description | |------|----------|---------|-------------| | --width | Yes | -- | Target width in pixels | | --height | Yes | -- | Target height in pixels | | --bias | No | 0.5 | 0.0=anchor top, 0.35=keep top, 0.5=center, 1.0=anchor bottom |

Background removal

python3 ~/.claude/scripts/nano-banana-process.py remove-bg \
    --bg-color 3a3a3a --tolerance 30 \
    sprite_raw.png sprite.png

| Flag | Default | Description | |------|---------|-------------| | --bg-color | 3a3a3a | Hex color to make transparent | | --tolerance | 30 | Color variance (0-255) |

Common background colors for Gemini prompts:

• 3a3a3a -- dark gray ("solid dark gray background")
• ffffff -- white ("solid white background")
• 000000 -- black ("solid black background")

Watermark removal

python3 ~/.claude/scripts/nano-banana-process.py remove-watermarks \
    --margin 40 --threshold 180 \
    input.png output.png

Format conversion

python3 ~/.claude/scripts/nano-banana-process.py convert \
    --format jpeg --quality 90 \
    input.png output.jpg

Formats: png (lossless, supports transparency), jpeg (smaller, no alpha), webp (best compression).

Full pipeline (chained processing)

Runs all steps in order: watermarks -> background -> crop -> format.

# Single file
python3 ~/.claude/scripts/nano-banana-process.py pipeline \
    --remove-watermarks --remove-bg --bg-color 3a3a3a \
    --width 256 --height 256 --bias 0.35 \
    --format png \
    input.png output.png

# Batch (input is a directory)
python3 ~/.claude/scripts/nano-banana-process.py pipeline \
    --width 400 --height 218 --bias 0.35 \
    --format jpeg --quality 90 \
    staging/originals/ output/cards/

9. End-to-end workflow examples

Generate + Process (single image)

# 1. Generate raw sprite
python3 ~/.claude/scripts/nano-banana-generate.py generate \
    --prompt "Full body warrior, Slay the Spire style, solid dark gray background..." \
    --output staging/warrior_raw.png \
    --model pro --aspect-ratio 1:1 \
    --save-original staging/originals/warrior.png

# 2. Process: remove watermarks, remove bg, crop, save as PNG
python3 ~/.claude/scripts/nano-banana-process.py pipeline \
    --remove-watermarks --remove-bg --bg-color 3a3a3a \
    --width 256 --height 256 --bias 0.35 \
    --format png \
    staging/warrior_raw.png output/warrior.png

Batch Generate + Batch Process

# 1. Create manifest
cat > enemies.json << 'EOF'
[
    {"id": "goblin", "prompt": "Full body goblin warrior..."},
    {"id": "skeleton", "prompt": "Full body skeleton archer..."}
]
EOF

# 2. Batch generate (saves originals)
python3 ~/.claude/scripts/nano-banana-generate.py batch \
    --manifest enemies.json \
    --output-dir staging/sprites/ \
    --originals-dir staging/originals/ \
    --model pro --skip-existing --delay 3

# 3. Batch process all generated sprites
python3 ~/.claude/scripts/nano-banana-process.py pipeline \
    --remove-watermarks --remove-bg --bg-color 3a3a3a \
    --width 256 --height 256 --bias 0.35 --format png \
    staging/sprites/ output/sprites/

Reprocess from originals (no regeneration cost)

# Try different crop dimensions without re-generating
python3 ~/.claude/scripts/nano-banana-process.py pipeline \
    --width 400 --height 167 --bias 0.35 --format jpeg --quality 90 \
    staging/originals/ output/cards/

Error Handling

Error: "GEMINI_API_KEY not set"

Solution: export GEMINI_API_KEY=your_key or export GOOGLE_API_KEY=your_key

Error: "No image in response"

Cause: Prompt may have triggered content safety filters, or API returned text-only. Solution: Adjust prompt. Check for policy-violating content. Try a different phrasing.

Error: "Missing dependency: google-genai"

Solution: pip install google-genai pillow

Error: "Rate limit exceeded (429)"

Solution: Increase --delay value. Default 2s may be too aggressive for free tier.

References

| Script | Path | Dependencies | |--------|------|-------------| | nano-banana-generate.py | ~/.claude/scripts/nano-banana-generate.py | google-genai, pillow | | nano-banana-process.py | ~/.claude/scripts/nano-banana-process.py | pillow |