Gemini Nano Banana 2 - Image Generation & Editing

Generate new images or edit existing ones using Google's Gemini Nano Banana 2 model (gemini-3.1-flash-image-preview) via the Gemini API. This is the latest and most capable Gemini image model, featuring advanced reasoning ("Thinking") with controllable levels, high-fidelity text rendering, Google Web + Image Search grounding, output from 512 up to 4K resolution, and 14 aspect ratios.

Usage

Run the script using absolute path (do NOT cd to skill directory first):

Generate new image:

uv run ~/.claude/skills/gemini-nano-banana-2/scripts/generate_image.py --prompt "your image description" --filename "output.png" [--aspect-ratio 1:1|1:4|1:8|2:3|3:2|3:4|4:1|4:3|4:5|5:4|8:1|9:16|16:9|21:9] [--resolution 512|1K|2K|4K] [--output-format png|webp|jpeg] [--response-modality text-and-image|image-only] [--thinking-level minimal|high] [--google-search] [--image-search] [--yes] [--cost-threshold 0.10] [--api-key KEY]

Edit existing image:

uv run ~/.claude/skills/gemini-nano-banana-2/scripts/generate_image.py --prompt "editing instructions" --filename "output.png" --input-image "path/to/input.png" [--aspect-ratio 1:1] [--resolution 2K] [--api-key KEY]

Edit with multiple reference images (compositing/style transfer, up to 14 images):

uv run ~/.claude/skills/gemini-nano-banana-2/scripts/generate_image.py --prompt "combine the subject from first image with the style of second image" --filename "output.png" --input-image "subject.png" --input-image "style-ref.png" [--resolution 2K] [--api-key KEY]

Generate with Google Web Search grounding (real-time data):

uv run ~/.claude/skills/gemini-nano-banana-2/scripts/generate_image.py --prompt "visualize the current weather forecast for San Francisco" --filename "output.png" --google-search --aspect-ratio 16:9 [--api-key KEY]

Generate with Google Image Search grounding (visual reference from the web):

uv run ~/.claude/skills/gemini-nano-banana-2/scripts/generate_image.py --prompt "a detailed painting of a resplendent quetzal bird resting on a flower" --filename "output.png" --image-search [--api-key KEY]

Generate with high thinking level (complex prompts):

uv run ~/.claude/skills/gemini-nano-banana-2/scripts/generate_image.py --prompt "A futuristic city built inside a giant glass bottle floating in space" --filename "output.png" --thinking-level high --resolution 2K [--api-key KEY]

Important: Always run from the user's current working directory so images are saved where the user is working, not in the skill directory.

Parameters

Aspect Ratio Options (14 ratios)

1:1 (default) - Square format
1:4 - Extreme vertical (banners)
1:8 - Ultra-extreme vertical
2:3 - Portrait
3:2 - Landscape
3:4 - Portrait (closer to square)
4:1 - Extreme horizontal (banners)
4:3 - Landscape (closer to square)
4:5 - Portrait (social media)
5:4 - Landscape (social media)
8:1 - Ultra-extreme horizontal
9:16 - Tall portrait (stories/reels)
16:9 - Wide landscape (presentations/video)
21:9 - Ultra-wide (cinematic)

Map user requests:

No mention of size/ratio -> 1:1
"square" -> 1:1
"portrait", "vertical", "tall" -> 2:3 or 9:16
"landscape", "horizontal", "wide" -> 3:2 or 16:9
"stories", "reels", "mobile" -> 9:16
"presentation", "video", "widescreen" -> 16:9
"cinematic", "ultra-wide" -> 21:9
"social media post" -> 4:5 (portrait) or 5:4 (landscape)
"banner", "header" -> 4:1 or 1:4 depending on orientation
"panoramic" -> 8:1

Resolution Options

512 - Small/thumbnail (~512px, fastest, lowest cost)
1K (default) - Standard quality (~1024px, fast)
2K - High quality (~2048px, good balance)
4K - Maximum quality (~4096px, slowest, highest cost)

Map user requests:

No mention of resolution -> 1K
"thumbnail", "icon", "small" -> 512
"high quality", "detailed", "high-res" -> 2K
"maximum quality", "4K", "ultra", "print quality" -> 4K
"quick", "fast", "draft" -> 512 or 1K

Output Format Options

png (default) - Lossless, supports transparency
webp - Smaller file size, supports transparency
jpeg - Smallest file size, no transparency

Map user requests:

No mention of format -> png
"small file", "compressed", "web" -> webp
"jpg", "jpeg", "photo" -> jpeg

Response Modality

text-and-image (default) - Returns both text description and image
image-only - Returns only the generated image, no text

Map user requests:

Default -> text-and-image
"just the image", "no text", "image only" -> image-only

Thinking Level

minimal (default) - Faster generation, good for simple prompts
high - Better quality for complex prompts with many elements, text rendering, or spatial relationships

Map user requests:

Default / simple prompts -> minimal
Complex scenes, precise text, many elements -> high
"think harder", "best quality", "complex" -> high

Google Web Search Grounding

--google-search flag enables Google Web Search grounding
Allows the model to use real-time web data when generating images
Useful for: current weather, recent events, factual infographics, stock charts, data visualizations

Map user requests:

"current", "today", "latest", "real-time", "up to date" -> add --google-search
Factual data requests (weather, news, sports scores) -> add --google-search
Creative/fictional prompts -> omit (not needed)

Google Image Search Grounding (Nano Banana 2 exclusive)

--image-search flag enables Google Image Search grounding
Allows the model to find and use web images as visual reference for generation
Useful for: accurate depictions of real species, landmarks, products, or people
Can be combined with --google-search for both web and image grounding

Map user requests:

"accurate", "realistic depiction of [real thing]" -> add --image-search
Requests for specific real-world subjects (animals, landmarks, products) -> add --image-search
Abstract/creative prompts -> omit (not needed)

Cost Warning & Auto-Approve

The script estimates request cost before calling the API
If estimated cost ≥ $0.10 (default threshold), it shows a breakdown and asks for confirmation
--yes / -y — Skip confirmation, auto-approve (always pass this flag so the user sees the prompt in their terminal)
--cost-threshold — Custom threshold in USD (default: 0.10)

Approximate per-image costs by resolution:

Resolution	Per Image
512	$0.045
1K	$0.067
2K	$0.101
4K	$0.151

Additional costs: thinking tokens (~~$0.006–$0.030), search grounding (~~$0.001), input images (~$0.0001 each). Requests at 2K or above will typically trigger the cost warning.

Important: Always pass --yes when calling from Claude so the user is not blocked by an interactive prompt they cannot see. Instead, inform the user of the estimated cost in your message before running the command. If the estimated cost would be high (2K+, 4K, high thinking), mention the approximate cost to the user first and ask if they want to proceed.

Input Images (editing, up to 14)

Use --input-image for each reference image (can repeat up to 14 times)
Up to 10 images of objects with high-fidelity detail preservation
Up to 4 images of characters for character consistency
Reference images by position in the prompt (e.g., "the person from the first image")

API Key

The script checks for API key in this order:

--api-key argument (use if user provided key in chat)
GEMINI_API_KEY environment variable
GOOGLE_API_KEY environment variable

If none is available, the script exits with an error message.

Filename Generation

Generate filenames with the pattern: yyyy-mm-dd-hh-mm-ss-name.{ext}

Format: {timestamp}-{descriptive-name}.{ext}

Timestamp: Current date/time in format yyyy-mm-dd-hh-mm-ss (24-hour format)
Name: Descriptive lowercase text with hyphens
Extension: Match the --output-format (.png, .webp, .jpg)
Keep the descriptive part concise (1-5 words typically)
Use context from user's prompt or conversation

Examples:

Prompt "A serene Japanese garden" -> 2025-12-17-14-23-05-japanese-garden.png
Prompt "sunset over mountains" (webp) -> 2025-12-17-15-30-12-sunset-mountains.webp
Prompt "current weather in NYC" (jpeg) -> 2025-12-17-16-45-33-nyc-weather.jpg

Image Editing

All editing uses the same generate_content API by passing input images alongside the text prompt. The model natively understands editing context.

Single Image Edit

When the user wants to modify an existing image:

Use --input-image parameter with the path to the image
The prompt should contain editing instructions (e.g., "make the sky more dramatic", "change to cartoon style")

Multi-Image Input (Compositing, Style Transfer & Character Consistency)

When the user wants to combine elements from multiple images:

Use --input-image multiple times (up to 14 images)
Reference images by order in the prompt (e.g., "apply the style of the second image to the first image")
For character consistency, provide multiple angles/poses of the same character

Common editing tasks: add/remove elements, change style, adjust colors, replace backgrounds, composite images, style transfer, character consistency across scenes, text overlay.

Prompt Handling

For generation: Pass user's image description as-is to --prompt. Only rework if clearly insufficient. The model excels at understanding natural language descriptions.

For editing: Pass editing instructions in --prompt (e.g., "add a rainbow in the sky", "make it look like a watercolor painting")

For multi-image: Reference images by position (e.g., "combine the person from the first image with the background of the second image")

For search-grounded: Include what real-time data is needed (e.g., "visualize the current weather forecast for the next 5 days in San Francisco")

Advanced text rendering: This model excels at generating legible text in images. When text is needed, first describe the text content clearly in the prompt (e.g., "a magazine cover with the title 'GEMINI' in bold serif font").

Preserve user's creative intent in all cases.

Thinking Mode

The model uses a built-in "Thinking" process that reasons through complex prompts. It generates interim "thought images" to refine composition before producing the final output.

minimal (default): Fast, sufficient for most prompts
high: Better quality for complex scenes, precise text, many elements

The thinking process:

Improves complex multi-element compositions
Helps with accurate text rendering
Refines layout and spatial relationships
Thinking tokens are billed regardless of output

Output

Saves image to current directory (or specified path if filename includes directory)
File extension is automatically matched to --output-format
If the model returns multiple images, files are numbered: name-1.ext, name-2.ext, etc.
Script outputs the full path(s) to the generated image(s)
Any text from the model (descriptions, explanations) is printed to stdout
Do not read the image back - just inform the user of the saved path(s)

Examples

Generate new image:

uv run ~/.claude/skills/gemini-nano-banana-2/scripts/generate_image.py --prompt "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep wrinkles and a warm smile, inspecting a freshly glazed tea bowl in his rustic workshop. Soft golden hour light, 85mm portrait lens, bokeh background." --filename "2025-12-17-14-23-05-japanese-ceramicist.png" --resolution 2K --aspect-ratio 2:3

Generate with text rendering (high thinking):

uv run ~/.claude/skills/gemini-nano-banana-2/scripts/generate_image.py --prompt "A glossy magazine cover with the large bold title 'NANO BANANA' in serif font. A person in a sleek minimal dress playfully holds the number 2. Issue number and 'Feb 2026' in the corner with a barcode. The magazine is on a shelf against an orange plastered wall." --filename "2025-12-17-14-25-30-magazine-cover.png" --resolution 4K --aspect-ratio 3:4 --thinking-level high

Generate with Google Web Search grounding:

uv run ~/.claude/skills/gemini-nano-banana-2/scripts/generate_image.py --prompt "Visualize the current weather forecast for the next 5 days in San Francisco as a clean, modern weather chart with outfit suggestions for each day" --filename "2025-12-17-14-26-00-sf-weather.png" --google-search --aspect-ratio 16:9 --resolution 2K

Generate with Google Image Search grounding:

uv run ~/.claude/skills/gemini-nano-banana-2/scripts/generate_image.py --prompt "A detailed painting of a resplendent quetzal bird resting on a flower, with a natural gradient background" --filename "2025-12-17-14-26-30-quetzal-painting.png" --image-search --aspect-ratio 3:2 --resolution 2K

Edit existing image (style transfer):

uv run ~/.claude/skills/gemini-nano-banana-2/scripts/generate_image.py --prompt "Transform this photograph into the artistic style of Vincent van Gogh's Starry Night, with swirling impasto brushstrokes and a palette of deep blues and bright yellows" --filename "2025-12-17-14-27-00-starry-night-style.png" --input-image "city-photo.jpg" --resolution 2K

Composite from multiple images:

uv run ~/.claude/skills/gemini-nano-banana-2/scripts/generate_image.py --prompt "Place the person from the first image into the beach scene from the second image, maintaining their appearance and clothing" --filename "2025-12-17-14-29-00-beach-composite.png" --input-image "person.png" --input-image "beach.png" --resolution 2K

Product mockup with logo:

uv run ~/.claude/skills/gemini-nano-banana-2/scripts/generate_image.py --prompt "Put this logo on a high-end advertisement for a premium perfume. The logo is perfectly integrated into the bottle design." --filename "2025-12-17-14-30-00-perfume-ad.png" --input-image "logo.png" --resolution 4K --aspect-ratio 3:4

Character consistency across scenes:

uv run ~/.claude/skills/gemini-nano-banana-2/scripts/generate_image.py --prompt "An office group photo of these people, they are making funny faces" --filename "2025-12-17-14-31-00-office-group.png" --input-image "person1.png" --input-image "person2.png" --input-image "person3.png" --aspect-ratio 5:4 --resolution 2K

Small thumbnail / icon:

uv run ~/.claude/skills/gemini-nano-banana-2/scripts/generate_image.py --prompt "A kawaii-style sticker of a happy red panda wearing a tiny bamboo hat, munching on a green bamboo leaf. Bold clean outlines, cel-shading, vibrant colors. White background." --filename "2025-12-17-14-32-00-red-panda-sticker.png" --resolution 512 --response-modality image-only

Ultra-wide cinematic banner:

uv run ~/.claude/skills/gemini-nano-banana-2/scripts/generate_image.py --prompt "A cinematic sci-fi landscape with a massive ring-shaped space station orbiting a gas giant, dramatic volumetric lighting" --filename "2025-12-17-14-33-00-space-banner.png" --aspect-ratio 21:9 --resolution 4K --thinking-level high