Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
gargantuax avatar

Nanobanana

  • 10.5k installs
  • 4 repo stars
  • Updated April 22, 2026
  • gargantuax/openskills

A Python CLI that calls Gemini image models to generate or edit images, with batch support, dry-run inspection, and custom endpoint routing.

About

Nanobanana is a Python CLI for Gemini-native image generation and editing across three model tiers (Nano Banana, Nano Banana 2, Nano Banana Pro). Developers use it for text-to-image requests, image-to-image editing with multiple local references, batch variant generation, and integration with custom Gemini-compatible gateways. Key workflows include single request generation, dry-run payload inspection before sending, batch runs with configurable output naming, and support for model-specific constraints (e.g., 512 resolution only on Nano Banana 2). Environment variables and CLI flags allow fine-grained control over authentication, base URLs, and image dimensions.

  • Single CLI for three Gemini image model tiers with automatic alias resolution (nanobanana, nanobanana-2, nanobanana-pro)
  • Batch generation with configurable count, output directory, and filename prefix for repeated variants
  • Image editing with repeated --input-image flags to pass multiple local file references
  • Dry-run mode to inspect final request payload before sending, reducing failed API calls
  • Custom Gemini-compatible gateway support via --base-url with auto and bearer authentication modes

Nanobanana by the numbers

  • 10,451 all-time installs (skills.sh)
  • +17 installs in the week ending Aug 5, 2026 (Skillselion tracking)
  • Ranked #83 of 1,335 Generative Media skills by installs in the Skillselion catalog
  • Security screen: LOW risk (skills.sh audit)
  • Data as of Aug 5, 2026 (Skillselion catalog sync)
At a glance

nanobanana capabilities & compatibility

Gemini API image generation pricing; varies by model tier and image size

Capabilities
text to image generation · image to image editing with local references · batch variant generation with configurable namin · dry run payload inspection · custom gemini compatible gateway routing · model alias resolution and validation · strict option validation per model
Use cases
image generation
Platforms
Windows · macOS · Linux
Runs
Runs locally
Pricing
Bring your own API key
From the docs

What nanobanana says it does

A single Python entrypoint for Gemini-native Nano Banana image generation and editing, with model aliases, strict option validation, batch runs, and custom endpoint support.
skill:gargantuax/openskills#nanobanana description
npx skills add https://github.com/gargantuax/openskills --skill nanobanana

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs10.5k
repo stars4
Security audit2 / 3 scanners passed
Last updatedApril 22, 2026
Repositorygargantuax/openskills

What it does

Generate and edit images using Gemini models with batch processing, local file references, and custom gateway support.

Who is it for?

Text-to-image generation, image-to-image editing with local references, batch variant creation, testing Gemini image APIs, custom gateway integration testing

Skip if: Real-time interactive image editing UI, streaming image generation, hosted SaaS image service, non-Gemini image models

When should I use this skill?

You need to generate or edit images using Gemini, batch-create variants, pass multiple local image references, test against a custom gateway, or inspect API payloads before sending.

What you get

Developers can generate and edit images via CLI with strict option validation, inspect payloads before sending, batch-generate variants, and route through custom gateways.

  • PNG image files
  • JSON response body (optional via --save-response)
  • batch output directory with prefixed images

By the numbers

  • Three model aliases: nanobanana, nanobanana-2, nanobanana-pro
  • Supports up to five variants in single batch command
  • Accepts repeated --input-image flags for multi-reference editing

Files

SKILL.mdMarkdownGitHub ↗

Nano Banana

A single Python entrypoint for Gemini-native Nano Banana image generation and editing, with model aliases, strict option validation, batch runs, and custom endpoint support.

Workflow

1. Open references/config.md to choose environment variables and override order. 2. Open references/models-and-api.md to pick the right Nano Banana tier and check model-specific constraints. 3. Prefer gemini-3.1-flash-image-preview (nanobanana-2) unless you need either the fastest low-cost default (nanobanana) or the highest-fidelity reasoning model (nanobanana-pro). 4. Run scripts/nanobanana.py generate for one request or scripts/nanobanana.py batch for repeated variants. 5. Add --dry-run first when the main risk is the payload shape, endpoint, or model-specific option support. 6. Pass --base-url or GEMINI_BASE_URL when you need a custom Gemini-compatible gateway. 7. Add --save-response <path> on generate when you need the raw JSON body for debugging.

Commands

Single text-to-image request:

python .\skills\nanobanana\scripts\nanobanana.py generate `
  --prompt "A retro-futurist product hero illustration for a developer tool" `
  --output .\out\hero.png `
  --model nanobanana-2 `
  --ratio 16:9 `
  --size 2K

Edit an existing image with two local references:

python .\skills\nanobanana\scripts\nanobanana.py generate `
  --prompt "Turn these references into a clean launch poster with legible title text" `
  --input-image .\refs\subject.png `
  --input-image .\refs\background.png `
  --output .\out\poster.png `
  --model nanobanana-pro `
  --ratio 4:5 `
  --size 2K

Use a custom Gemini-compatible gateway:

python .\skills\nanobanana\scripts\nanobanana.py generate `
  --prompt "A bold mascot sticker pack" `
  --output .\out\stickers.png `
  --base-url http://your-gateway.example.com/v1beta `
  --auth-mode bearer

Batch-generate five variants:

python .\skills\nanobanana\scripts\nanobanana.py batch `
  --prompt "Minimal app icon for a PDF workflow product" `
  --count 5 `
  --dir .\out\icons `
  --prefix icon `
  --model nanobanana `
  --ratio 1:1

Inspect the final request without sending it:

python .\skills\nanobanana\scripts\nanobanana.py generate `
  --prompt "An editorial illustration of AI agents at work" `
  --model nanobanana-2 `
  --output .\out\agents.png `
  --dry-run

Rules

  • --model accepts the aliases nanobanana, nanobanana-2, and nanobanana-pro, or an exact Gemini model ID.
  • nanobanana resolves to gemini-2.5-flash-image, nanobanana-2 resolves to gemini-3.1-flash-image-preview, and nanobanana-pro resolves to gemini-3-pro-image-preview.
  • image_size is only valid on Gemini 3 image models; nanobanana rejects --size.
  • 512 resolution is only valid on nanobanana-2.
  • Process environment variables override .env; CLI flags override both.
  • Never print secrets.
  • generate accepts repeated --input-image paths for image editing or multi-reference generation.
  • --base-url should point to the Gemini API root such as https://generativelanguage.googleapis.com/v1beta, not directly to /models/....
  • --auth-mode auto uses x-goog-api-key for the official Google endpoint and sends both Authorization: Bearer and x-goog-api-key for custom endpoints to maximize gateway compatibility.

Resources

  • Script: scripts/nanobanana.py
  • Config reference: references/config.md
  • Models and API reference: references/models-and-api.md

Related skills

How it compares

Choose nanobanana for Gemini-native agent image CLI; use other generative media skills when you need non-Gemini providers or video pipelines.

FAQ

Which Gemini image model should I use?

Prefer gemini-3.1-flash-image-preview (nanobanana-2) for balance. Use nanobanana (gemini-2.5-flash-image) for fastest/cheapest. Use nanobanana-pro (gemini-3-pro-image-preview) for highest fidelity.

Can I use multiple image references in one generation?

Yes, pass repeated --input-image flags to provide multiple local file references for image editing or multi-reference generation.

How do I test against a custom Gemini gateway?

Pass --base-url pointing to your gateway root (e.g., https://your-gateway.example.com/v1beta) and set --auth-mode to auto or bearer.

Is Nanobanana safe to install?

skills.sh reports 2 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.

Generative Mediallmautomation

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.