nanobanana-skill

Nanobanana Image Skill

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

Requirements

1. GEMINI_API_KEY in ~/.nanobanana.env (GEMINI_API_KEY=sk-dummy) or the shell environment.
2. Python dependencies from requirements.txt.
3. The executable is nanobanana.py in this same skill directory. Resolve its absolute path once before running it.

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

Defaults

Model gemini-3.1-flash-image-preview, search grounding on, thinking summaries on at level high, resolution 1K, and no aspect ratio unless the request implies a shape. Do not make the user choose a model, search mode, or thinking mode unless they asked for that level of control.

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

Worth overriding: --model gemini-3-pro-image-preview for very detail-heavy or typography-sensitive work (slower); --resolution 512px for quick ideation (Nanobanana 2 models only), 2K/4K for polished deliverables; --thinking-level low when latency beats refinement; search off when the user wants a purely imaginative result. Run python3 /absolute/path/to/nanobanana.py --help for the exact accepted values, including the full aspect-ratio and model lists.

Run it

Generate from text:

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

Edit or composite — pass every reference with --input. Nanobanana 2 mixes multiple references well, so do not narrow a blend, lineup, storyboard, or consistency pass down to a single image:

python3 /absolute/path/to/nanobanana.py \
  --prompt "Turn these product photos into a clean 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, saving the model's text and metadata alongside the image:

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" \
  --text-output /absolute/path/to/output/cover.txt \
  --metadata-output /absolute/path/to/output/cover.json \
  --output /absolute/path/to/output/cover.png

Then report the saved path(s), whether search grounding stayed enabled, where any text or thought summaries landed, and any warning from the run. If the model returns text but no image, say so plainly and suggest a more explicitly image-focused prompt rather than presenting the run as a success.

Prompting

Good Nanobanana prompts are production briefs, not art wishes: subject, visual style, composition or camera framing, any required text, the output's use case, and constraints such as brand colors, negative space, or realism level.

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.

For edits, say what to preserve as well as 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.

When a run fails

Check credential presence without printing its value, input readability, and output writability. For an unsupported option, consult the helper's accepted values. Correct assistant-chosen options within the requested result, but do not silently switch a user-selected model or provider. Before a bounded retry, check whether the earlier attempt already produced output; report the actual error if recovery would require new authority or changing the request.