Nano Banana Image Generation

Generate and edit images using Google's Gemini image models. This skill ships the
pi-nano-banana CLI (a TypeScript wrapper — no Python) that resolves the
GEMINI_API_KEY for you and delegates to @the-focus-ai/nano-banana.

Prerequisites

• GEMINI_API_KEY set via the environment or a gitignored .env in the project
  or package directory (the CLI resolves it automatically).
• Network access — the underlying @the-focus-ai/nano-banana CLI is fetched via npx.

Quick Reference

Prefer the bundled pi-nano-banana bin (auto key resolution, output-dir creation):

# Generate a new image
pi-nano-banana "a serene mountain landscape at sunset"

# Edit an existing image
pi-nano-banana "add a hot air balloon to the sky" --file photo.jpg

# Specify output path
pi-nano-banana "a minimalist logo" --output logo.png

# Use a specific model / faster flash model
pi-nano-banana "detailed illustration" --model gemini-2.0-flash-exp
pi-nano-banana "a quick sketch" --flash

The raw CLI still works if you prefer it (npx @the-focus-ai/nano-banana "…").
For batch generation from code, import batchGenerate from
@blackbelt-technology/pi-dashboard-nano-banana/nano-banana.js.

Workflow

Step 1: Understand the Request

Before generating, clarify:

• Subject: What should be in the image?
• Style: Photorealistic, illustration, cartoon, abstract?
• Mood: Bright, dark, moody, cheerful?
• Composition: Close-up, wide shot, specific aspect ratio?
• Use case: Hero image, icon, social media, print?

Step 2: Craft an Effective Prompt

Read references/prompting-guide.md for comprehensive guidance.

Key principles:

1. Be specific and descriptive
2. Include style references
3. Specify what you DON'T want
4. Describe composition and framing

Example — Weak prompt:

"a cat"

Example — Strong prompt:

"A fluffy orange tabby cat curled up on a velvet armchair, soft afternoon sunlight streaming through a window, warm cozy interior, photorealistic style, shallow depth of field"

Step 3: Generate the Image

npx @the-focus-ai/nano-banana "your detailed prompt here"

Default output: output/generated-<timestamp>.png

Step 4: Iterate

If the result isn't right:

1. Refine the prompt — Add more detail or constraints
2. Edit the image — Use --file to modify the generated image
3. Try a different model — Some models handle certain styles better

Commands

Text-to-Image Generation

npx @the-focus-ai/nano-banana "<prompt>"

Image Editing

npx @the-focus-ai/nano-banana "<edit instruction>" --file <input-image>

Edit instructions should describe the change:

• "Remove the background and replace with a gradient"
• "Add sunglasses to the person"
• "Change the sky to sunset colors"
• "Make it look like a watercolor painting"

Options

Option	Description
--file <image>	Input image for editing
--output <path>	Custom output path
--model <name>	Specific Gemini model
--flash	Use gemini-2.0-flash (faster, simpler images)
--prompt-file <path>	Read prompt from file
--list-models	Show available models
--api-key <key>	Explicit Gemini key
--backend gemini|pi	Backend (default gemini; pi is opt-in, see below)

pi backend (opt-in, OpenRouter)

--backend pi (or NANO_BANANA_BACKEND=pi) generates through pi's own model
runtime instead of the Gemini CLI — no GEMINI_API_KEY needed.

• Credential: sign in to OpenRouter in pi (/login openrouter) or set OPENROUTER_API_KEY.
• Requires @earendil-works/pi-coding-agent >= 1.0.0 resolvable next to this package.
• Opt-in only: a missing Gemini key never falls back to pi; library callers
  (e.g. the video-production storyboard) stay on Gemini unless they pass backend: "pi".
• Models are OpenRouter image ids. Bare Gemini ids get google/ in front
  (--model gemini-3-pro-image → google/gemini-3-pro-image); non-Google models
  need the full vendor/model id (black-forest-labs/flux.2-pro). Default
  google/gemini-2.5-flash-image; --flash maps to google/gemini-3.1-flash-lite-image.
  gemini-2.0-flash-exp does not exist there — an unknown id lists the known ones.
• Cost: the success line prints (pi · <model>) · ~$<cost> est. — an estimate
  computed from token usage, not the billed amount.

pi-nano-banana "a red fox in the snow, watercolor" -o fox.png --backend pi
pi-nano-banana "make it night" --file fox.png -o fox-night.png --backend pi

Best Practices

For Better Results

1. Start with composition: Describe the layout first, then details
2. Use artistic references: "in the style of Studio Ghibli", "like a National Geographic photo"
3. Specify lighting: "golden hour lighting", "dramatic chiaroscuro", "soft diffused light"
4. Include negative guidance: Describe what to avoid in the prompt itself
5. Consider aspect ratio: The model generates square by default; describe wide/tall if needed

For Editing

1. Be specific about changes: "Add a blue butterfly to the top-left corner"
2. Preserve what works: "Keep the background unchanged, only modify the foreground"
3. Iterative refinement: Make one change at a time for better control

Environment Setup

Ensure GEMINI_API_KEY is set:

export GEMINI_API_KEY="your-api-key-here"

Or create a .env file in your project:

GEMINI_API_KEY=your-api-key-here

Troubleshooting

Problem	Solution
"No image in response"	Prompt may have triggered safety filters — rephrase
Poor quality results	Add more specific style guidance, use gemini-2.0-flash-exp
--backend pi: "Provider is not configured"	Run /login openrouter in pi or set OPENROUTER_API_KEY
--backend pi: "needs @earendil-works/pi-coding-agent >= 1.0.0"	Install/update pi next to the package
Image doesn't match description	Be more explicit about composition, add negative constraints