Nano Banana Pro JSON

Nano Banana Pro JSON - Advanced Image Generation

Generate and edit images using Google's Nano Banana Pro API with structured JSON control, style presets, and photorealistic enhancement.

Usage

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

uv run ~/.claude/skills/nano-banana-pro-json/scripts/generate_image.py --prompt "description" --filename "output.png" [options]

Important: Always run from the user's current working directory so images save where the user is working.

Do not read an image file before editing it. Pass its path to --input-image and let the script send it. Reading it first spends the whole file through the context window and changes nothing about the result.

If uv isn't found (uv: command not found — non-interactive shells often drop ~/.local/bin or the Homebrew bin from PATH), resolve it and call it explicitly rather than giving up. This script needs uv (third-party deps: google-genai, pillow), so plain python3 is not a fallback here:

UV="$(command -v uv || ls "$HOME/.local/bin/uv" "$HOME/.cargo/bin/uv" /opt/homebrew/bin/uv /usr/local/bin/uv 2>/dev/null | head -1)"
"$UV" run ~/.claude/skills/nano-banana-pro-json/scripts/generate_image.py --prompt "..." --filename "..."

Simple Mode

Works identically to the original nano-banana-pro skill:

uv run ~/.claude/skills/nano-banana-pro-json/scripts/generate_image.py --prompt "A serene Japanese garden" --filename "2025-11-23-14-23-05-japanese-garden.png"

Style Presets

Use --style-preset NAME to apply a curated camera/lighting/composition profile:

Example:

uv run ~/.claude/skills/nano-banana-pro-json/scripts/generate_image.py \
  --prompt "portrait of a woman in a garden" \
  --filename "2025-11-23-14-23-05-studio-portrait.png" \
  --style-preset photorealistic-studio

Logos & brand identity

Logos are a distinct mode — flat, iconic, scalable, the opposite of the photographic presets above. When the user wants a logo, brand mark, wordmark, or brand identity, follow the brand-brief recipe in references/logo-brand-identity.md: take a short brief (name, industry, personality, colors, logo type, icon concept), construct a logo-appropriate prompt (flat vector, minimal, strong silhouette, limited palette — explicitly away from photorealism/3D/gradients), generate a batch of varied concepts at --aspect-ratio 1:1 --resolution 2K (no photographic --style-preset, no --photorealistic), run the proof checklist (monochrome, favicon-size, spelling, originality), iterate via --input-image one change at a time, then vectorize the winner to SVG for free (vtracer/potrace — the step every paid logo tool charges for).

Boundary: the generator makes a raster concept (the recipe's Step 5 traces it to production SVG locally). It does not do trademark clearance or confirm font licensing, and text can slip — verify a wordmark's spelling.

Product & marketing images

For product shots, e-commerce catalog images, lifestyle scenes, and ad creative, follow references/product-marketing.md. It's photographic (the presets help), and adds the product-specific discipline: e-commerce specs (pure #FFFFFF bg, product fills 70-90%, per-platform aspect ratios), identity-lock when you pass a real product via --input-image ("preserve exact appearance; do not reinterpret"), consistent shot sets (lock lighting/angle, vary one element), and on-image text.

Boundary: for a real product it can subtly alter details — verify the render against reality, and never render fabricated prices/claims/label text or brand-impersonation imagery.

Infographics & explanatory diagrams

For infographics, explainers, and process/comparison diagrams, follow references/infographics-diagrams.md: pick a layout matching the content's shape (timeline / pyramid / hub-and-spoke / comparison / funnel / cross-section) and a named style (corporate-flat, isometric, blueprint…), supply every label and number verbatim in quotes, and proofread the output.

Boundary: it renders the look of an infographic, not trustworthy data — it garbles text and invents numbers. Supply the facts and verify them; for real data viz use the report-builder skill, not this.

JSON Configuration

Use --json-config with a file path or inline JSON string:

# Inline JSON
uv run ~/.claude/skills/nano-banana-pro-json/scripts/generate_image.py \
  --prompt "mountain landscape" \
  --filename "output.png" \
  --json-config '{"style_parameters":{"camera":{"focal_length":"24mm","aperture":"f/8"}}}'

# File path
uv run ~/.claude/skills/nano-banana-pro-json/scripts/generate_image.py \
  --prompt "mountain landscape" \
  --filename "output.png" \
  --json-config config.json

Full JSON Schema

{
  "prompt": "optional - CLI --prompt always takes precedence",
  "consistency_id": "character name for consistency across generations",
  "style_parameters": {
    "camera": {
      "type": "DSLR",
      "model": "Sony A7III",
      "focal_length": "85mm",
      "aperture": "f/1.4",
      "shutter_speed": "1/200s",
      "iso": "100"
    },
    "lighting": {
      "type": "Studio",
      "setup": "Three-point lighting",
      "direction": "Front-angled key light",
      "color_temperature": "5500K"
    },
    "composition": {
      "framing": "Medium close-up",
      "perspective": "Eye-level",
      "depth_of_field": "Shallow"
    }
  },
  "output_settings": {
    "aspect_ratio": "16:9",
    "format": "png"
  }
}

All fields are optional. Only include what you want to control.

Aspect Ratio

Use --aspect-ratio to guide composition (applied as prompt text, not API parameter):

Choices: 1:1, 4:3, 16:9, 9:16, 3:2, 2:3, 4:5, 3:4

uv run ~/.claude/skills/nano-banana-pro-json/scripts/generate_image.py \
  --prompt "cityscape at dusk" \
  --filename "output.png" \
  --aspect-ratio 16:9

Can also be set via JSON output_settings.aspect_ratio. CLI flag takes precedence.

Photorealistic Enhancement

Use --photorealistic to auto-inject quality markers (8k, ultra-sharp, hyperrealistic, visible pores, natural skin texture, etc.):

uv run ~/.claude/skills/nano-banana-pro-json/scripts/generate_image.py \
  --prompt "portrait of an elderly fisherman" \
  --filename "output.png" \
  --photorealistic

Combining Options

All options can be combined. Precedence rules:

1. Prompt: CLI --prompt always wins over JSON prompt field
2. Aspect ratio: CLI --aspect-ratio wins over JSON output_settings.aspect_ratio
3. Style: Preset provides base defaults, JSON config overrides specific fields via deep merge
4. Photorealistic: Additive -- markers are appended regardless of other settings

Example combining everything:

uv run ~/.claude/skills/nano-banana-pro-json/scripts/generate_image.py \
  --prompt "portrait of a woman on a rooftop at sunset" \
  --filename "2025-11-23-14-23-05-rooftop-portrait.png" \
  --style-preset cinematic \
  --json-config '{"style_parameters":{"camera":{"focal_length":"35mm"}},"consistency_id":"Elena"}' \
  --photorealistic \
  --aspect-ratio 16:9 \
  --resolution 4K

Resolution

The Gemini 3 Pro Image API supports three resolutions (uppercase K required):

• 1K (default) - ~1024px resolution
• 2K - ~2048px resolution
• 4K - ~4096px resolution

Map user requests:

• No mention of resolution -> 1K
• "low resolution", "1080", "1080p", "1K" -> 1K
• "2K", "2048", "normal", "medium resolution" -> 2K
• "high resolution", "high-res", "hi-res", "4K", "ultra" -> 4K

API Key

Checked in order:

1. --api-key argument
2. GEMINI_API_KEY environment variable

Filename Generation

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

• Timestamp: Current date/time in yyyy-mm-dd-hh-mm-ss (24-hour format)
• Name: Descriptive lowercase text with hyphens
• Extension: .png (default), .jpg, or .webp based on JSON config output_settings.format

Examples:

• 2025-11-23-14-23-05-japanese-garden.png
• 2025-11-23-15-30-12-sunset-mountains.jpg

Image Editing

When modifying an existing image:

1. Use --input-image with the path to the source image
2. --prompt contains editing instructions
3. All style/preset/photorealistic options work with editing too

uv run ~/.claude/skills/nano-banana-pro-json/scripts/generate_image.py \
  --prompt "make it look like a cinematic film still" \
  --filename "2025-11-23-14-25-30-cinematic-edit.png" \
  --input-image "original-photo.jpg" \
  --style-preset cinematic

Output Formats

Set via JSON config output_settings.format, filename extension, or --webp flag:

• png (default) - Lossless
• jpg/jpeg - JPEG (lossy, configurable quality)
• webp - WebP (lossy, configurable quality) - converted from Gemini's native PNG/JPEG output via PIL

WebP notes: The Gemini API does not natively export WebP. The script receives the image as PNG/JPEG from the API and converts it to WebP using PIL. This adds a negligible conversion step but produces smaller files with good quality.

WebP convenience flag

Use --webp to force WebP output regardless of filename extension:

uv run ~/.claude/skills/nano-banana-pro-json/scripts/generate_image.py \
  --prompt "sunset over ocean" \
  --filename "2025-11-23-14-23-05-sunset.png" \
  --webp

This saves as 2025-11-23-14-23-05-sunset.webp (extension auto-corrected).

Quality control

Use --quality (1-100, default 80) to control JPEG/WebP compression:

# High quality WebP
uv run ~/.claude/skills/nano-banana-pro-json/scripts/generate_image.py \
  --prompt "detailed macro photo" \
  --filename "output.webp" \
  --quality 95

# Smaller file size
uv run ~/.claude/skills/nano-banana-pro-json/scripts/generate_image.py \
  --prompt "web thumbnail" \
  --filename "output.webp" \
  --quality 60

Quality has no effect on PNG output (always lossless).

Format precedence

1. --webp flag (highest)
2. JSON config output_settings.format
3. Filename extension
4. Default: PNG

Examples

Simple generation:

uv run ~/.claude/skills/nano-banana-pro-json/scripts/generate_image.py \
  --prompt "A cat wearing a tiny hat" \
  --filename "2025-11-23-14-23-05-cat-hat.png"

Studio portrait with preset:

uv run ~/.claude/skills/nano-banana-pro-json/scripts/generate_image.py \
  --prompt "professional headshot of a young CEO" \
  --filename "2025-11-23-14-23-05-ceo-headshot.png" \
  --style-preset photorealistic-studio \
  --photorealistic \
  --resolution 4K

Cinematic landscape with custom JSON:

uv run ~/.claude/skills/nano-banana-pro-json/scripts/generate_image.py \
  --prompt "misty mountain valley at dawn" \
  --filename "2025-11-23-14-23-05-mountain-dawn.png" \
  --json-config '{"style_parameters":{"camera":{"focal_length":"24mm","aperture":"f/11"},"lighting":{"setup":"Soft diffused dawn light","color_temperature":"4000K warm"}}}' \
  --aspect-ratio 16:9 \
  --resolution 4K

Nostalgic film edit:

uv run ~/.claude/skills/nano-banana-pro-json/scripts/generate_image.py \
  --prompt "add warm film grain and a slight vignette" \
  --filename "2025-11-23-14-23-05-nostalgic-edit.png" \
  --input-image "modern-photo.jpg" \
  --style-preset nostalgic-film

Provenance

This skill calls Google's Gemini image API ("Nano Banana Pro" / Gemini 3 Pro Image) via the official google-genai SDK, and converts output formats with Pillow (PIL). It requires your own GEMINI_API_KEY — no key is bundled or stored in the skill. Not affiliated with or endorsed by Google; Google's API terms, pricing, and content policies apply.