nanobanana-skill

Nanobanana Image Skill

Use the bundled nanobanana.py tool to generate or edit images with Gemini image models. The default path now targets Nano Banana 2 (gemini-3.1-flash-image-preview) and turns on thinking summaries plus Google Search grounding by default, because those defaults are the main reason to use this skill instead of a generic image prompt.

When to use this skill

Use it for:

1. Creating a new image from text
2. Editing or remixing one or more existing images
3. Combining several reference images into one composition
4. Requests where factual freshness matters and image grounding should use live web data
5. Requests that need strong text rendering, layout reasoning, or more deliberate composition

Do not use it for:

1. Non-image tasks
2. Image work that explicitly must use another provider or another installed image skill

Requirements

1. GEMINI_API_KEY must exist in ~/.nanobanana.env or the shell environment.
2. Python dependencies from requirements.txt must be installed.
3. The executable is the nanobanana.py file in this same skill directory. Resolve its absolute path once before running it.

The CLI can display --help without credentials. It validates local input files before creating an API client and exits non-zero when the API returns no image.

Example env file:

GEMINI_API_KEY=sk-dummy

Default behavior

Unless the user explicitly asks otherwise, prefer these defaults:

1. Model: gemini-3.1-flash-image-preview
2. Search grounding: enabled
3. Thinking summaries: enabled
4. Thinking level: high
5. Resolution: 1K
6. Aspect ratio: leave unspecified unless the user clearly wants a shape

Leaving aspect ratio unspecified is usually better for edits because Gemini can match the input image shape. For text-only generation, pick an aspect ratio only when the user implies a format such as poster, square post, banner, phone wallpaper, or ultrawide hero image.

Workflow

1. Clarify only the missing constraints

Ask only for details that materially affect the result:

1. The image brief or editing instruction
2. Any input/reference images to use
3. Target format or aspect ratio if implied by the use case
4. Output filename if the user cares where it lands

Do not force the user to choose a model, search mode, or thinking mode unless they asked for that level of control. The latest Nanobanana 2 path is already the default.

2. Choose the right mode

Use generate when there are no input images.

Use edit/composite when there are one or more input images. Nanobanana 2 can mix multiple references, so do not artificially limit the task to a single image if the user is clearly asking for a blend, lineup, storyboard, or consistency pass.

3. Run the bundled tool

Use the script beside this skill file.

Basic generation:

python3 /absolute/path/to/nanobanana.py \
  --prompt "Create a high-end coffee bag package design with tactile paper texture and clear typography" \
  --output /absolute/path/to/output/package.png

Editing or compositing:

python3 /absolute/path/to/nanobanana.py \
  --prompt "Turn these product photos into a clean 4:5 ecommerce hero image with a soft studio shadow and subtle headline area" \
  --input /absolute/path/to/ref1.png /absolute/path/to/ref2.png \
  --aspect-ratio 4:5 \
  --output /absolute/path/to/output/hero.png

Grounded generation with saved text metadata:

python3 /absolute/path/to/nanobanana.py \
  --prompt "Use Google Search to ground an editorial illustration about the most recent lunar mission and create a clean magazine cover concept" \
  --aspect-ratio 2:3 \
  --text-output /absolute/path/to/output/cover.txt \
  --metadata-output /absolute/path/to/output/cover.json \
  --output /absolute/path/to/output/cover.png

4. Return the result clearly

Always tell the user:

1. The saved image path or paths
2. Whether search grounding stayed enabled
3. Whether text/thought summaries were saved anywhere
4. Any relevant limitation or warning from the run

If the model returns text but no image, report that plainly and suggest a more explicit image-focused prompt instead of pretending the run succeeded.

Recommended options

Models

1. gemini-3.1-flash-image-preview: default. Best default for fast, high-volume image generation and editing with Nanobanana 2 features.
2. gemini-3-pro-image-preview: slower, but a good override for very detail-heavy or typography-sensitive work.
3. gemini-2.5-flash-image: legacy fallback if the user specifically wants the older Nanobanana model.

Aspect ratios

Supported ratios:

1. 1:1
2. 1:4
3. 1:8
4. 2:3
5. 3:2
6. 3:4
7. 4:1
8. 4:3
9. 4:5
10. 5:4
11. 8:1
12. 9:16
13. 16:9
14. 21:9

Quick picks:

1. 1:1 for logos, icons, thumbnails, and general social posts
2. 4:5 for feed posts and product cards
3. 2:3 for posters and book-cover style work
4. 9:16 for stories, shorts, and phone wallpaper
5. 16:9 or 21:9 for slides, banners, and desktop hero art
6. 1:4, 4:1, 1:8, 8:1 for very tall or very wide experimental layouts now supported by Nanobanana 2

Resolution

1. 512px: Nanobanana 2 only. Best for quick ideation.
2. 1K: default. Good tradeoff for most requests.
3. 2K: use for polished deliverables.
4. 4K: use when the user explicitly needs a high-resolution final.

Thinking and search

1. Keep search grounding on by default when the request could benefit from live facts, current events, or real product references.
2. Keep thinking summaries on by default because Nanobanana 2 often composes better on multi-constraint tasks.
3. Lower --thinking-level to low or minimal when the user prioritizes latency over refinement.
4. Disable search only when the user wants a purely imaginative result or explicitly requests no web grounding.

Prompting guidance

Good Nanobanana prompts are direct production briefs, not vague art wishes. Include:

1. Subject
2. Visual style
3. Composition or camera framing
4. Required text if any
5. Output use case
6. Constraints such as brand colors, empty space, or realism level

Prefer prompts like:

Create a premium sparkling water can advertisement. Use a cold studio product-photo look, silver highlights, condensation droplets, and a clean dark-teal background. Leave negative space in the upper-right for headline copy.

Instead of:

make a cool drink ad

For edits, tell the model what to preserve and what to change:

Keep the shoe silhouette and logo placement intact. Replace the background with a bright outdoor basketball court, add dynamic afternoon shadows, and keep the image looking like a real sports campaign photo.

Nanobanana 2 capabilities to lean on

1. Multi-reference composition with many input images
2. Better grounded visuals with Google Search and Google Image Search support behind the built-in search tool
3. Wider aspect-ratio support, including very tall and very wide outputs
4. 512px fast ideation output in addition to 1K, 2K, and 4K
5. Stronger iterative reasoning via Gemini 3 thinking controls

Error handling

If the run fails:

1. Check ~/.nanobanana.env and confirm GEMINI_API_KEY is present.
2. Confirm each input image path exists and is readable.
3. Confirm the output directory is writable.
4. If a feature looks unsupported, retry with gemini-3.1-flash-image-preview first.
5. If the response contains only text, rewrite the prompt so the image deliverable is explicit.

Examples

Fast ideation

python3 /absolute/path/to/nanobanana.py \
  --prompt "Create three-dimensional sticker-style fruit mascots on white" \
  --resolution 512px \
  --output /absolute/path/to/output/stickers.png

Grounded current-events visual

python3 /absolute/path/to/nanobanana.py \
  --prompt "Use Google Search to ground a newspaper-style illustration about the latest Mars mission and create a restrained front-page visual" \
  --aspect-ratio 3:2 \
  --output /absolute/path/to/output/mars.png

Multi-reference composite

python3 /absolute/path/to/nanobanana.py \
  --prompt "Create a single brand moodboard from these references. Keep the ceramic texture from the first image, the palette from the second, and the lighting mood from the third." \
  --input /absolute/path/to/a.png /absolute/path/to/b.png /absolute/path/to/c.png \
  --aspect-ratio 16:9 \
  --output /absolute/path/to/output/moodboard.png