Nano Banana Pro (Gemini 3 Pro Image)

Generate and edit professional-quality images using Google's state-of-the-art Gemini 3 Pro Image model.

API Configuration

Set your Gemini API key as an environment variable:

export GEMINI_API_KEY="your-api-key-here"

Get your API key at: https://aistudio.google.com/apikey

Quick Start

Test API Connection

Before generating images, verify API credentials:

python scripts/test_connection.py --api-key YOUR_KEY

Or set environment variable:

export GEMINI_API_KEY="your-api-key-here"
python scripts/test_connection.py

Generate Image from Text

python scripts/generate_image.py "A futuristic cityscape at sunset, neon lights, cyberpunk style"

With options:

python scripts/generate_image.py "Portrait of a cat" \
  --aspect-ratio 9:16 \
  --temperature 0.7 \
  --output ./my_images \
  --filename cat_portrait

Edit Existing Image

python scripts/edit_image.py "Make the sky more dramatic with storm clouds" input.jpg

With options:

python scripts/edit_image.py "Change car color to red" photo.png \
  --aspect-ratio 16:9 \
  --output ./edited \
  --filename red_car

Core Workflows

1. Text-to-Image Generation

When to use: Creating images from scratch based on text descriptions.

Process:

1. Craft effective prompt using best practices from references/prompting-guide.md
2. Run generation script with appropriate parameters
3. Review output and iterate if needed

Example:

# High-quality product photography
python scripts/generate_image.py \
  "High-end product photography of luxury watch on black marble, dramatic single key light from top-left, reflective surface, macro lens, f/5.6, commercial quality, 4K" \
  --aspect-ratio 1:1 \
  --temperature 0.5

Key considerations:

• Use specific, detailed prompts (see Prompting Best Practices)
• Choose appropriate aspect ratio for use case
• Lower temperature (0.3-0.5) for consistency, higher (0.8-1.0) for creativity
• Iterate with multi-turn editing for complex requirements

2. Image Editing & Refinement

When to use: Modifying existing images with natural language instructions.

Process:

1. Identify specific changes needed
2. Use precise editing instructions with action verbs (Add, Change, Make, Remove, Replace)
3. Run edit script with source image
4. Chain multiple edits for complex transformations

Example - Single Edit:

python scripts/edit_image.py \
  "Add flying birds in the upper right sky" \
  landscape.jpg \
  --output ./edited

Example - Multi-turn refinement:

# Edit 1: Change time of day
python scripts/edit_image.py "Convert to sunset lighting" day_scene.jpg \
  --output ./step1 --filename sunset

# Edit 2: Add elements using output from step 1
python scripts/edit_image.py "Add warm street lamps glowing" ./step1/sunset_image_0_0.jpg \
  --output ./step2 --filename with_lamps

# Edit 3: Fine-tune atmosphere
python scripts/edit_image.py "Make the sky more orange and dramatic" ./step2/with_lamps_image_0_0.jpg \
  --output ./final --filename final

Key considerations:

• Be specific about which elements to change
• Use positional language ("in the background", "on the left")
• Keep original aspect ratio unless intentionally changing
• Each edit builds on previous result

3. Batch Generation

When to use: Generating multiple variations or different images in sequence.

Process:

Create a shell script or Python wrapper:

#!/bin/bash
# batch_generate.sh

PROMPTS=(
  "Modern office workspace, minimalist design"
  "Cozy coffee shop interior, warm lighting"
  "Professional meeting room, corporate aesthetic"
)

for i in "${!PROMPTS[@]}"; do
  python scripts/generate_image.py "${PROMPTS[$i]}" \
    --output ./batch_output \
    --filename "scene_$i" \
    --aspect-ratio 16:9

  echo "Generated image $((i+1))/${#PROMPTS[@]}"
  sleep 2  # Rate limiting
done

4. Reference-Based Generation

When to use: Maintaining style consistency or character consistency across images.

Process:

1. Prepare reference images (up to 14 images)
2. Create prompt referencing style/character to maintain
3. Use Python SDK or API directly for multi-image upload

Example using Python:

from generate_image import NanoBananaProClient
from pathlib import Path
import base64

client = NanoBananaProClient(api_key="YOUR_KEY")

# Read reference images
ref_images = []
for img_path in ["ref1.jpg", "ref2.jpg", "ref3.jpg"]:
    with open(img_path, "rb") as f:
        img_data = base64.b64encode(f.read()).decode()
        ref_images.append({
            "inlineData": {
                "mimeType": "image/jpeg",
                "data": img_data
            }
        })

# Generate with references
# (Requires direct API call with multiple inlineData parts)

Prompting Best Practices

Essential Structure

Follow this formula for best results:

[Subject] + [Style/Medium] + [Lighting Details] + [Camera/Composition] + [Quality Modifiers]

Example:

"Portrait of elderly craftsman | Documentary photography style | Soft window light from left | 85mm lens, f/2.8, shallow DOF | Professional editorial quality, sharp focus on eyes"

Key Principles

1. Be Specific: Vague prompts → generic results

   • ❌ "a sunset"
   • ✅ "golden hour sunset over mountain range, vibrant orange and purple clouds, silhouetted pine trees in foreground"

2. Use Cinematic Language: Nano Banana Pro responds well to photography terms

   • Lens: "24mm wide-angle" | "85mm portrait" | "200mm telephoto"
   • Lighting: "soft diffused" | "harsh direct" | "backlit with rim lighting"
   • Camera: "low-angle shot" | "overhead view" | "Dutch angle tilt"

3. Layer Descriptions: Build depth with atmosphere, materials, mood

   • "Cozy library, warm amber lighting, leather chairs, rain visible through tall windows, steam rising from tea cup on oak table"

4. Iterate with Multi-Turn: Start simple, refine progressively

   • Turn 1: "Modern kitchen, white cabinets"
   • Turn 2: "Add marble countertops"
   • Turn 3: "Make the lighting warmer, golden hour through windows"

Cinematic Digital Painting Style

For documentary-style digital paintings with warm golden lighting, painterly brush strokes, and atmospheric depth, see the dedicated style guide:

cinematic-style.md - Complete formula, key elements, examples, and technical notes

Quick reference:

• Warm golden/amber lighting with dramatic rim lighting
• Painterly brush strokes with visible texture
• Soft bokeh depth-of-field for atmospheric background blur
• High contrast (deep blacks + bright highlights)
• Temperature: 0.6 for balanced consistency/creativity

For complete prompting guide, see: references/prompting-guide.md

Script Reference

generate_image.py

Generate images from text prompts.

Parameters:

• prompt (required): Text description of image
• --api-key: API key (or use GEMINI_API_KEY env var)
• --aspect-ratio: 1:1 | 3:4 | 4:3 | 9:16 | 16:9 (default: 16:9)
• --temperature: 0.0-1.0 (default: 0.7)
• --output: Output directory (default: ./output)
• --filename: Base filename (default: generated)
• --verbose: Show full API response

Common use cases:

# Quick generation
python scripts/generate_image.py "red sports car"

# High-quality consistent output
python scripts/generate_image.py "professional headshot" \
  --temperature 0.4 --aspect-ratio 3:4

# Creative exploration
python scripts/generate_image.py "abstract art" --temperature 0.9

# Debug mode
python scripts/generate_image.py "test prompt" --verbose

edit_image.py

Edit existing images with natural language instructions.

Parameters:

• prompt (required): Edit instruction
• image (required): Path to input image
• `