nanobanana

name	nanobanana
description	Generate and edit images using Google Gemini (Nano Banana Pro / Nano Banana 2). Automatically selects the best model based on prompt complexity. Supports text-to-image generation, image editing with reference images, configurable aspect ratios, 1K/2K/4K output, Google Search grounding, and batch generation. Works with both Gemini Developer API and Vertex AI.

Nano Banana - AI Image Generation Skill

Use the Python scripts in scripts/ to generate and edit images via Google Gemini. The model is automatically selected based on prompt complexity:

Model	ID	When used
Nano Banana Pro	gemini-3-pro-image-preview	Complex or high-quality requests
Nano Banana 2	gemini-3.1-flash-image-preview	Simple, lightweight requests

Nano Banana Pro is auto-selected when any of these conditions are met (OR):

• --pro flag is specified
• Prompt contains quality keywords (e.g. 高品質, 高精細, プロ, professional, photorealistic)
• Prompt is 100+ characters long
• 2 or more input images
• 4K resolution requested
• Google Search grounding enabled

Prerequisites

1. Install dependencies

pip install google-genai Pillow

2. Configure API credentials (one of the following)

Option A: Gemini Developer API (recommended for personal use)

Set the GEMINI_API_KEY environment variable. Get a key at https://aistudio.google.com/apikey

export GEMINI_API_KEY="your-api-key"

Option B: Vertex AI API (for Google Cloud users)

Set GOOGLE_CLOUD_PROJECT and optionally GOOGLE_CLOUD_LOCATION. Requires a GCP project with the Vertex AI API enabled and Application Default Credentials configured (gcloud auth application-default login).

export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"   # optional, defaults to us-central1

Priority: If both GOOGLE_CLOUD_PROJECT and GEMINI_API_KEY are set, Vertex AI is used.

3. Optional environment variables

Variable	Default	Description
NANOBANANA_MODEL	(auto)	Force a specific model (overrides auto-selection)
IMAGE_OUTPUT_DIR	./nanobanana-images	Default output directory
NANOBANANA_NO_SSL_VERIFY	(unset)	Set to 1 / true / yes to disable SSL certificate verification

---

Scripts

scripts/generate.py - Single image generation / editing

Text-to-image

python scripts/generate.py "a cute robot mascot, pixel art style" -o robot.png

Image editing (with reference image)

python scripts/generate.py "make the sky purple and add stars" -i photo.jpg -o edited.png

Multiple reference images (up to 14)

python scripts/generate.py "group photo of these people at a party" \
  -i person1.png -i person2.png -i person3.png -o group.png

With aspect ratio and resolution

python scripts/generate.py "cinematic landscape, dramatic lighting" \
  --ratio 21:9 --size 4K -o landscape.png

With Google Search grounding (for real-world accuracy)

python scripts/generate.py "photo of the Eiffel Tower at sunset" \
  --search -o eiffel.png

Disable SSL verification (for corporate proxies or self-signed certs)

python scripts/generate.py "abstract art" --no-ssl-verify -o art.png

JSON output (for programmatic use)

python scripts/generate.py "abstract art" --json -o art.png

Full options

usage: generate.py [-h] [-o OUTPUT] [-i INPUTS] [-r RATIO] [-s SIZE]
                   [--search] [-v] [--json] [--no-ssl-verify] prompt

Arguments:
  prompt              Text prompt for image generation

Options:
  -o, --output PATH   Output file path (auto-generated if omitted)
  -i, --input PATH    Input image for editing (repeatable, up to 14)
  -r, --ratio RATIO   Aspect ratio: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
  -s, --size SIZE     Resolution: 1K, 2K, 4K
  --search            Enable Google Search grounding
  --pro               Force Nano Banana Pro model
  -v, --verbose       Show detailed output
  --json              Output result as JSON
  --no-ssl-verify     Disable SSL certificate verification

---

scripts/batch_generate.py - Batch image generation

Generate multiple image variations from a single prompt.

Basic batch

python scripts/batch_generate.py "pixel art logo" -n 20 -d ./logos -p logo

High-res batch with aspect ratio

python scripts/batch_generate.py "product photo, white background" \
  -n 10 --ratio 1:1 --size 4K -d ./products

Parallel execution (faster)

python scripts/batch_generate.py "icon set" -n 20 --parallel 5 -d ./icons

Full options

usage: batch_generate.py [-h] [-n COUNT] [-d DIR] [-p PREFIX] [-r RATIO]
                         [-s SIZE] [--search] [--delay DELAY]
                         [--parallel N] [-q] [--json] [--no-ssl-verify] prompt

Arguments:
  prompt              Text prompt for image generation

Options:
  -n, --count N       Number of images (default: 10)
  -d, --dir DIR       Output directory (default: ./nanobanana-images)
  -p, --prefix STR    Filename prefix (default: image)
  -r, --ratio RATIO   Aspect ratio
  -s, --size SIZE     Resolution: 1K, 2K, 4K
  --search            Enable Google Search grounding
  --delay SECS        Delay between sequential requests (default: 3)
  --parallel N        Concurrent requests (default: 1, max recommended: 5)
  -q, --quiet         Suppress progress output
  --json              Output results as JSON
  --no-ssl-verify     Disable SSL certificate verification

---

Aspect Ratio Guide

Ratio	Typical use
1:1	Icons, avatars, social media posts
4:3	Presentations, traditional photos
3:2	Standard landscape photos
2:3	Portrait photos
16:9	Banners, YouTube thumbnails, widescreen
9:16	Phone wallpapers, Instagram stories
21:9	Cinematic ultra-wide
4:5	Instagram portrait posts
5:4	Group photos
3:4	Book covers, portrait art

Resolution Guide

Size	Description
1K	Standard resolution
2K	High resolution
4K	Ultra high resolution (best for print and large displays)

---

Prompting Tips

Good prompts include:

1. Subject - What to generate ("a robot", "sunset over mountains")
2. Style - Art style ("pixel art", "watercolor", "photorealistic")
3. Details - Specific qualities ("warm lighting", "minimalist", "vibrant colors")

Examples of effective prompts:

• "Professional product photo of wireless headphones on marble, soft studio lighting, 85mm lens"
• "Pixel art robot mascot, 8-bit style, blue and orange, transparent background"
• "Minimalist logo, geometric mountain shape, blue gradient, flat design, clean edges"

See references/prompts.md for a comprehensive prompt reference with category-specific templates.

---

Error Handling

Error	Solution
google-genai package not installed	Run pip install google-genai Pillow
No API credentials found	Set GEMINI_API_KEY or GOOGLE_CLOUD_PROJECT
Content blocked by safety filters	Rephrase the prompt to avoid restricted content
API rate limit reached	Wait and retry; use --delay for batch operations
Image file not found	Verify the -i input path is correct
SSL: CERTIFICATE_VERIFY_FAILED	Use --no-ssl-verify or set NANOBANANA_NO_SSL_VERIFY=1