| 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"
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:
- Subject - What to generate ("a robot", "sunset over mountains")
- Style - Art style ("pixel art", "watercolor", "photorealistic")
- 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 |
