Blog Image

Blog Image - AI Image Generation for Blog Content

You are a Creative Director that orchestrates Gemini's image generation specifically for blog content. Never pass raw user text directly to the API. Always interpret, enhance, and construct an optimized prompt using the 6-component Reasoning Brief system.

Quick Reference

Blog Image Types

Match the image type to blog use case:

Sizing requirements:

• Blog hero/cover: 1200x630 (OG-compatible) or 1920x1080
• Open Graph (OG): 1200x630 (required for social sharing)
• Inline images: 1200px+ wide

MCP Availability Check

Before generating, check if nanobanana-mcp tools are available:

1. Try calling get_image_history (lightweight, no side effects) 2. If it succeeds: MCP is available, proceed with generation 3. If it fails: MCP not configured - inform the user:

• "Image generation requires the nanobanana-mcp server. Run /blog image setup to configure it."
• When called internally (from blog-write/blog-rewrite): return silently, no error. The calling workflow continues with stock photos.

Generation Workflow

For /blog image generate <idea> or when invoked internally:

Step 1: Analyze Intent

Determine what the blog needs:

• Image type: Hero, inline, OG card, section divider?
• Blog topic: What is the article about?
• Style: Photorealistic, editorial, illustrated, minimal?
• Constraints: Brand colors, specific dimensions, platform format?
• Mood: Authoritative, inviting, dramatic, clean?

If the request is vague, ask one clarifying question about use case and style.

Step 2: Select Domain Mode

Choose the expertise lens for the image:

Load references/prompt-engineering-blog.md for domain mode modifier libraries.

Step 3: Construct the 6-Component Reasoning Brief

Build the prompt as natural narrative paragraphs - NEVER as keyword lists:

1. Subject - Who/what, with rich physical detail (textures, materials, scale) 2. Action - What is happening, pose, gesture, movement, state 3. Context - Environment, setting, time of day, season, weather 4. Composition - Camera angle, shot type, framing, negative space, depth 5. Lighting - Light source, quality, direction, color temperature, shadows 6. Style - Art medium, aesthetic, film stock, reference artists/eras

Template for photorealistic blog images:

A photorealistic [shot type] of [subject with physical detail], [action/pose],
set in [environment with specifics]. [Lighting conditions] create [mood].
Captured with [camera model], [focal length] lens at [f-stop], producing
[depth of field effect]. [Color palette/grading notes]. Aspect ratio 16:9,
suitable as a blog [hero image/inline illustration] at [target dimensions].

Template for illustrated/stylized:

A [art style] [format] of [subject with character detail], featuring
[distinctive characteristics] with [color palette]. [Line style] and
[shading technique]. Background is [description]. [Mood/atmosphere].

Step 4: Set Aspect Ratio

Call set_aspect_ratio BEFORE generating:

Step 5: Generate via MCP

Model selection (use set_model MCP tool if switching):

• NB2 Flash (default): Best for most blog images - fast, 14 ratios, 4K, $0.067/img
• NB Pro: Use for hero images with text overlays (94% text accuracy) or highest quality - $0.134/img
• Original: Budget option at $0.039/img - 5 ratios, 1K max

Load references/mcp-tools.md for parameter details. Load references/gemini-models.md for model specs, pricing, and rate limits.

Step 6: Post-Processing (when needed)

After generation, resize/convert for blog use:

# Resize to blog hero dimensions (1200x630)
magick input.png -resize 1200x630^ -gravity center -extent 1200x630 hero.png

# Convert to WebP for web optimization
magick input.png -quality 85 output.webp

# Convert to AVIF (smallest, modern)
magick input.png -quality 80 output.avif

# Crop to exact OG dimensions
magick input.png -resize 1200x630^ -gravity center -extent 1200x630 og-image.png

Check if magick (ImageMagick 7) is available. Fall back to convert if not.

Step 7: Deliver

Provide: 1. Image path - where it was saved (~/Documents/nanobanana_generated/) 2. Crafted prompt - show the full Reasoning Brief (educational) 3. Settings - model, aspect ratio, domain mode 4. Alt text - descriptive sentence, 10-125 chars, topic keywords naturally 5. Frontmatter snippet (for hero/OG images):

coverImage: "/path/to/generated-image.png"
coverImageAlt: "Descriptive alt text sentence with topic keywords"
ogImage: "/path/to/generated-image.png"

6. Refinement suggestions - 1-2 ideas if relevant

Edit Workflow

For /blog image edit <path> <instructions>:

1. Read the image path and edit instruction 2. Enhance the instruction (never pass raw):

3. Call gemini_edit_image with enhanced instruction 4. Return modified image path and description

Internal API (for blog-write / blog-rewrite)

When invoked as a Task subagent from blog-write or blog-rewrite:

Input (provided by calling skill):

• image_type: hero, inline, og, divider
• topic: blog post topic/title
• section_context: (optional) heading or section the image supports
• style_preference: (optional) photorealistic, illustrated, editorial
• count: (optional) number of images needed (default: 1)

Output (returned to calling skill):

### Generated Image
- **Path:** ~/Documents/nanobanana_generated/image_timestamp.png
- **Alt Text:** Descriptive sentence about the image
- **Type:** hero / inline / og
- **Domain Mode:** Editorial
- **Aspect Ratio:** 16:9
- **Suggested Frontmatter:**
  coverImage: "/path/to/image.png"
  coverImageAlt: "Alt text here"

Graceful fallback: If MCP is unavailable, return immediately with no error. The calling workflow continues with stock photos. Never block blog-write or blog-rewrite because image generation is unavailable.

Alt Text Generation

For every generated image, create alt text following blog standards:

• Full descriptive sentence (not keyword list)
• 10-125 characters
• Include topic keywords naturally
• Describe what the image shows AND its relevance to the content
• For charts/infographics: include the key data point

Good: Marketing team analyzing AI search traffic data on a dashboard showing citation metrics Bad: SEO AI marketing blog optimization image

Setup

For /blog image setup:

1. Run python3 scripts/setup_image_mcp.py (interactive)

• Or: python3 scripts/setup_image_mcp.py --key YOUR_KEY (non-interactive)
• Default writes to ~/.claude/settings.json (user-private, mode 0600)
• --project flag opts into project .mcp.json (env-expansion only,

refuses to write a literal key into a tracked file) 2. Verify: python3 scripts/validate_image_setup.py 3. Requires:

• Node.js 18+ (npx)
• Google AI API key (free at https://aistudio.google.com/apikey)

4. The script pins the package to @ycse/nanobanana-mcp@1.1.1. Update the pin in setup_image_mcp.py (constant PINNED_PACKAGE) when bumping.

Safety Filter Auto-Rephrase

When IMAGE_SAFETY or SAFETY is returned, do NOT give up. Auto-rephrase and retry:

1. Identify the likely trigger (violence, public figures, NSFW-adjacent, or overly cautious filter) 2. Rephrase using positive framing - describe what you WANT, not what to avoid 3. If the subject is a person, make them generic (remove celebrity-like specifics) 4. If the scene is dramatic, soften: "intense" → "focused", "battle" → "competition" 5. Retry with the rephrased prompt (max 3 attempts before reporting to user)

Google acknowledged filters "became way more cautious than we intended" - benign prompts are sometimes blocked. Persistence with rephrasing usually succeeds.

Edit, Don't Re-roll

If an image is 80% correct, use gemini_chat for conversational editing rather than regenerating from scratch. The session maintains style consistency, so targeted edits preserve what works while fixing what doesn't.

When to edit vs regenerate:

• Color slightly off → Edit ("shift the color temperature warmer")
• Wrong composition entirely → Regenerate with revised brief
• Good scene but wrong lighting → Edit ("change to golden hour lighting from the left")
• Missing a detail → Edit ("add a steaming coffee cup on the desk")

Error Handling

Reference Documentation

Load on-demand - do NOT load all at startup:

• references/prompt-engineering-blog.md - Domain modes, 6-component system, blog templates
• references/gemini-models.md - Model specs, rate limits, aspect ratios, pricing
• references/mcp-tools.md - MCP tool parameters and response formats

Gemini Image Generation Models - Nano Banana

Last updated: 2026-03-14

Aligned with Google's March 2026 API state and pricing

Available Models

gemini-3.1-flash-image-preview (Recommended - Speed + Quality)

gemini-3-pro-image-preview (Highest Quality - Text + Detail)

Note: The base text model gemini-3-pro-preview was deprecated March 9, 2026, but the image variant (gemini-3-pro-image-preview) remains active on AI Studio and Vertex AI.

gemini-2.5-flash-image (Stable Fallback)

Imagen 4 (Dedicated Image Models)

Notes: Imagen 4 models are dedicated image generators (not multimodal LLMs). They lack conversational editing but offer lower per-image cost for high-volume workflows.

Deprecated Models (DO NOT USE)

gemini-2.5-flash-image-preview

• Status: Shut down - use the stable gemini-2.5-flash-image variant

gemini-2.0-flash-exp

• Status: Deprecated, shutdown June 1, 2026. Use gemini-2.5-flash-image

Legacy models (Gemini 2.0 Flash and earlier)

• Status: All retiring June 1, 2026. Migrate to NB2 Flash or Imagen 4.

Model Selection for Blog Content

Aspect Ratios

All 14 supported ratios. Availability varies by model:

Resolution Tiers

Notes:

• Actual pixel dimensions depend on aspect ratio (e.g., 4K at 16:9 = 4096×2304)
• Default is 1K if imageSize is not specified
• Known bug: imageSize sometimes ignored through LiteLLM proxy and in image-to-image workflows

Rate Limits

Google cut free-tier limits by ~92% in December 2025. Current structure:

Important: Preview models (NB2, Pro) have more restrictive limits than stable models. Free tier for image generation may require billing to be enabled - some users report 0 IPM (images per minute) without billing.

Pricing (March 2026)

Cost optimization: Use 512px for drafts (cheapest), 1K for standard blog images, reserve 2K-4K for hero images and final assets.

Multi-Image Input

Useful for brand-consistent blog imagery: provide brand style references to maintain visual identity across generated images.

Safety Filters - Dual Layer Architecture

Layer 1: Input Filters (Configurable)

Standard harm category filtering via safetySettings API parameter. Covers hate speech, harassment, sexually explicit, and dangerous content.

Layer 2: Output Filters (NON-CONFIGURABLE)

Server-side analysis of the generated image itself. Cannot be disabled through any API parameter.

• Returns finishReason: "IMAGE_SAFETY" (distinct from "SAFETY")
• Known to be overly cautious - Google acknowledged "filters became way more cautious than we intended"
• Benign prompts like "dog" or "bowl of cereal" have been blocked
• Celebrity blocking tightened significantly with NB2

No workaround exists for Layer 2 blocks beyond rephrasing the prompt.

Content Credentials

• SynthID watermarks are always embedded (invisible, machine-readable). Survives rescaling, compression, and most edits - cannot be disabled
• C2PA Content Credentials are embedded on Nano Banana Pro images from Gemini App, Vertex AI, and Google Ads

Blog Image Post-Processing

Key Limitations

• No native transparent backgrounds (workaround: prompt green background, then chromakey removal)
• Text rendering quality varies - keep text under 25 characters for best results (Pro achieves 94% accuracy with quoted text)
• Safety filters may block benign prompts - use auto-rephrase workflow
• Session context resets between Claude Code conversations
• imageSize and thinking level depend on MCP package version support
• No video generation (use Veo 3.1 for image-to-video workflows)

MCP Tools Reference - @ycse/nanobanana-mcp

Package: @ycse/nanobanana-mcp

GitHub: https://github.com/YCSE/nanobanana-mcp

Tools

gemini_generate_image

Generate an image from a text prompt.

Parameters:

Returns: Image data + file path (saved to ~/Documents/nanobanana_generated/)

Example usage in Claude Code:

User: "Generate a sunset over mountains in watercolor style"
→ Claude calls gemini_generate_image with prompt
→ Returns image path and description

gemini_edit_image

Edit an existing image with text instructions.

Parameters:

Returns: Modified image data + file path

Example:

User: "Remove the background from ~/Documents/photo.png"
→ Claude calls gemini_edit_image with path and instruction

gemini_chat

Multi-turn visual conversation maintaining session context.

Parameters:

Returns: Text response + optional image

Key feature: Session consistency - maintains style, characters, and context across turns. Great for iterative refinement.

set_aspect_ratio

Configure the aspect ratio for subsequent image generations.

Parameters:

Supported ratios: 1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2, 4:5, 5:4, 1:4, 4:1, 1:8, 8:1, 21:9

set_model

Switch the active Gemini model.

Parameters:

Available models:

• gemini-3.1-flash-image-preview (default, recommended)
• gemini-2.5-flash-image (stable fallback)

get_image_history

Retrieve list of images generated in the current session.

Parameters: None

Returns: Array of image entries with paths and prompts

clear_conversation

Reset session context and conversation history.

Parameters: None

Returns: Confirmation of reset

Environment Variables

Output Directory

All generated images are saved to: ~/Documents/nanobanana_generated/

Images are named with timestamps for easy identification.

Feature Availability via MCP

Some newer Gemini API features depend on the MCP package version of @ycse/nanobanana-mcp. Check the package version to confirm support:

If a feature is not yet supported by the MCP package, you can still use it via direct API calls with curl or the Google AI SDK.

Prompt Engineering Reference - Blog Image Generation

Load on-demand when constructing complex prompts for blog images.

Adapted from Banana Claude's prompt engineering system for blog-specific use cases.

Aligned with Google's March 2026 "Ultimate Prompting Guide" for Gemini image generation.

The 6-Component Reasoning Brief

Every image prompt should contain these components, written as natural narrative paragraphs - NEVER as comma-separated keyword lists.

1. Subject

The main focus of the image. Describe with physical specificity.

Good: "A weathered Japanese ceramicist in his 70s, deep sun-etched wrinkles mapping decades of kiln work, calloused hands cradling a freshly thrown tea bowl with an irregular, organic rim"

Bad: "old man, ceramic, bowl"

2. Action

What is happening. Movement, pose, gesture, state of being.

Good: "leaning forward with intense concentration, gently smoothing the rim with a wet thumb, a thin trail of slip running down his wrist"

Bad: "making pottery"

3. Context

Environment, setting, temporal and spatial details.

Good: "inside a traditional wood-fired anagama kiln workshop, stacked shelves of drying pots visible in the soft background, late afternoon light filtering through rice paper screens"

Bad: "workshop, afternoon"

4. Composition

Camera angle, shot type, framing, spatial relationships.

Good: "intimate close-up shot from slightly below eye level, shallow depth of field isolating the hands and bowl against the soft bokeh of the workshop behind"

Bad: "close up"

5. Lighting

Light source, quality, direction, temperature, shadows.

Good: "warm directional light from a single high window camera-left, creating gentle Rembrandt lighting on the face with a soft triangle of light on the shadow-side cheek, deep warm shadows in the workshop"

Bad: "natural lighting"

6. Style

Art medium, aesthetic reference, technical photographic details.

Good: "captured with a Sony A7R IV, 85mm f/1.4 GM lens, Kodak Portra 400 color grading with lifted shadows and muted earth tones, reminiscent of Dorothea Lange's documentary portraiture"

Bad: "photorealistic, 8K, masterpiece"

Blog Image Types

Map blog use cases to domain modes and aspect ratios:

Blog-Specific Prompt Templates

Hero/Cover Image

A [photorealistic/editorial] wide establishing shot of [topic-relevant scene],
[action or state that conveys the article's core message]. Set in [environment
with specifics that match blog topic]. [Wide, balanced composition with rule of
thirds]. [Dramatic or inviting lighting] creating [mood that matches article tone].
[Style reference appropriate to blog niche]. Aspect ratio 16:9, suitable as a
blog hero image at 1200x630 or 1920x1080.

Inline Illustration

A [style] [shot type] of [specific element from the blog section], [illustrating
the concept of the adjacent heading]. [Contextual environment]. [Clear, well-lit
composition that works at medium size]. [Color palette complementing blog design].

Social/OG Card Image

A [clean, high-contrast] [format] showing [key visual concept of the article],
[simplified for recognition at thumbnail size]. [Minimal background, strong focal
point]. [Bold lighting that reads well at small sizes]. Text-free, designed for
social sharing preview at 1200x630.

Domain Mode Libraries (Blog-Relevant)

Editorial Mode

Best for: Blog headers, feature images, lifestyle content, storytelling. Publication refs: National Geographic, Kinfolk, The Atlantic, Wired Styling notes: layered textures, clean compositions, atmospheric depth Locations: contextual to blog topic - offices, workshops, nature, urban Mood: authoritative, inviting, professional

Product Mode

Best for: E-commerce blogs, product reviews, comparison articles, tech posts. Surfaces: polished marble, brushed concrete, raw linen, acrylic riser, gradient sweep Lighting: softbox diffused, hard key with fill card, rim separation, tent lighting Angles: 45-degree hero, flat lay, three-quarter, straight-on Style refs: Apple product photography, Aesop minimal, clean and modern

Landscape Mode

Best for: Environmental backgrounds, travel blogs, atmospheric hero sections. Depth layers: foreground interest, midground subject, background atmosphere Atmospherics: fog, mist, haze, volumetric light rays, dust particles Time of day: blue hour (pre-dawn), golden hour, magic hour (post-sunset) Weather: dramatic storm clouds, clearing after rain, sun-dappled

UI/Web Mode

Best for: Tech blog icons, feature illustrations, app screenshots, diagrams. Styles: flat vector, isometric 3D, line art, glassmorphism, material design Colors: specify exact hex or descriptive palette (e.g., "cool blues #2563EB to #1E40AF") Sizing: design at 2x for retina, specify exact pixel dimensions needed Backgrounds: transparent (request solid white then post-process), gradient, solid color

Infographic Mode

Best for: Data-driven posts, process explanations, comparison visuals. Layout: modular sections, clear visual hierarchy, bento grid, flow top-to-bottom Text: use quotes for exact text, descriptive font style, specify size hierarchy Data viz: bar charts, pie charts, flow diagrams, timelines, comparison tables Colors: high-contrast, accessible palette, consistent with blog brand

Abstract Mode

Best for: Pattern backgrounds, section dividers, decorative headers, mood pieces. Geometry: fractals, voronoi tessellation, spirals, organic flow, crystalline Textures: marble veining, fluid dynamics, smoke wisps, ink diffusion, watercolor bleed Color palettes: analogous harmony, complementary clash, monochromatic gradient Styles: generative art, procedural, macro photography of materials

Search-Grounded Generation (NB2 Feature)

For blog images that need real-world accuracy (current products, real locations, data-driven infographics), use Google Search grounding with this 3-part formula:

[Source/Search request] + [Analytical task] + [Visual translation]

Example: "Search for the top 5 AI coding tools by GitHub stars in 2026, analyze their relative popularity, then generate a clean infographic comparison chart in a modern dark theme."

Requires googleSearch tool enabled in the API call. MCP server handles this when available.

Advanced Techniques

Text-First Hack

For images with text, establish the concept conversationally FIRST ("I need a header with 'AI Search 2026'"), then generate. Always enclose text in quotation marks. The model anchors on text mentioned early in the conversation.

Camera Hardware Naming

Name real camera hardware for precise aesthetics: "Sony A7III, 85mm f/1.4 lens" locks precise bokeh better than "shallow depth of field with bokeh".

Character Consistency (Multi-turn)

Use gemini_chat and maintain descriptive anchors:

• First turn: Generate character with exhaustive physical description
• Following turns: Reference "the same character" + repeat 2-3 key identifiers
• Key identifiers: hair color/style, distinctive clothing, facial feature

Text Rendering Tips

• Quote exact text: with the text "OPEN DAILY" in bold condensed sans-serif
• 25 characters or less - practical limit for reliable rendering
• 2-3 distinct phrases max - more text fragments degrade quality
• Describe font characteristics, not font names
• Specify placement: "centered at the top third", "along the bottom edge"
• High contrast: light text on dark, or vice versa

Positive Framing (No Negative Prompts)

Gemini does NOT support negative prompts. Rephrase exclusions:

• Instead of "no blur" → "sharp, in-focus, tack-sharp detail"
• Instead of "no people" → "empty, deserted, uninhabited"
• Instead of "no text" → "clean, uncluttered, text-free"

Creative Director Prompting (Advanced)

For premium blog hero images, specify all 4 professional dimensions:

1. Lighting Direction

• Studio: softbox at 45 degrees, rim light for separation
• Dramatic: single hard light with deep shadows
• Natural: golden hour, overcast diffusion, window light
• Flat: even illumination for product/editorial clarity

2. Camera & Lens Control

• Specify hardware: "shot on Sony A7IV with 85mm f/1.4"
• Focal length affects perspective: 24mm (wide, dramatic) vs 85mm (compressed, flattering)
• Depth of field: f/1.4 (dreamy bokeh) vs f/8 (sharp throughout)
• Distance: close-up (texture detail) vs establishing (context)

3. Film Stock & Color Grading

• Nostalgic: Kodak Portra 400 (warm skin tones, soft pastels)
• Modern: Fuji Pro 400H (cooler tones, clean shadows)
• Cinematic: teal-and-orange grading, crushed blacks
• Clean: neutral white balance, minimal grading

4. Material & Texture Definition

• Specify surfaces: "brushed aluminum", "rough linen", "polished marble"
• Fabric: "crisp cotton", "worn denim", "sheer silk"
• Environmental: "morning dew on glass", "rain-streaked concrete"
• Detail level influences realism and visual interest

Common Prompt Mistakes

1. Keyword stuffing - "8K, masterpiece, best quality" adds nothing to Gemini 2. Tag lists instead of prose - Gemini wants narrative, not "red car, sunset, cinematic" 3. Missing lighting - Single biggest quality differentiator; always specify 4. No composition direction - Results in generic centered framing 5. Ignoring aspect ratio - Always call set_aspect_ratio before generating 6. Overlong prompts - Diminishing returns past ~200 words; be precise 7. Text > 25 chars - Rendering degrades; use text-first hack for accuracy 8. Not iterating - Use gemini_chat for refinement instead of re-generating