/blog-image

name: blog-image
description: >
  Paid Gemini image generation for blog heroes, inline illustrations, and OG
  cards (direct API by default, optional MCP for edits). Asks for explicit
  consent before the first paid call. Runs only on an explicit request:
  /blog image, "generate a blog hero image", "blog illustration", "edit this
  blog image", "OG image", or when blog-write or blog-rewrite needs a hero.
  Not for charts (blog-chart) or stock-photo search.
user-invocable: true
argument-hint: "[generate|edit|setup] [description-or-path]"
license: MIT
metadata:
  author: AgriciDaniel
  version: "2.3.2"
  optional-mcp-package: "@ycse/nanobanana-mcp"

Blog Image - AI Image Generation for Blog Content

Bundled paths below use host Markdown substitution of `${CLAUDE_SKILL_DIR}`; it is not an exported shell variable. Resolve them before execution, quote paths, and refuse nonabsolute overrides. Pass `blog_reference_root` resolved from `${CLAUDE_SKILL_DIR}/../blog/references`, `blog_template_root` from `${CLAUDE_SKILL_DIR}/../blog/templates`, and needed sibling roots to agents. Read the main reference `orchestration-details.md` before loading project context; pass only its helper-fenced output to downstream agents.

Cost and consent gate (mandatory, read first)

This skill spends the user's Google AI credit and writes image files.

• **What it spends:** one paid Gemini image call per generated or edited

image. `generate_hero.py` can try up to four model IDs in turn when the first fails, so budget for that worst case. The stock-photo and Openverse rungs are free but may need their own keys.

• **Cost basis:** per-image prices at

https://ai.google.dev/gemini-api/docs/pricing. On 2026-10-12 that page listed `gemini-nano-banana-2.1` at $0.0336 (1K), $0.0504 (2K), $0.113 (4K) and `gemini-3.1-flash-image` at $0.067 (1K). Re-read it before quoting a number.

• **What it writes:** `hero.<ext>` and `hero-credit.txt` in the draft folder

(direct API), `~/Documents/nanobanana_generated/` (optional MCP), and `~/.claude/settings.json` (setup only).

• **Consent:** before the FIRST paid call or file write in a session, tell

the user the model, size, image count, and estimated cost (count times price) and wait for an explicit yes. The yes covers only that count. Asking for a blog post does not by itself consent to a paid image call.

• **No uncapped spend:** never loop on paid calls. Safety rephrases stop at 3

attempts per image. Bulk work (for example a cluster) needs a stated total count and a cap, confirmed once before the first call.

• **Declined or unavailable:** skip the Gemini call (run the script without

`--allow-paid`, its default, so a key is ignored and it uses the free rungs: existing hero, then stock keys, then Openverse) and return ONE line for the orchestrator's "Fallbacks and skips" summary, such as "Hero image: user declined paid generation, used a stock photo".

The default route builds one fixed editorial prompt from the topic and tags, so it needs no brief from you. Custom prompt briefs, domain modes and image edits exist only on the optional MCP route, documented in `${CLAUDE_SKILL_DIR}/references/mcp-route.md` (load it only for that route).

Quick Reference

| Command | What it does | |---------|-------------| | `/blog image generate <idea>` | Generate a hero-style blog image (default route), or a custom brief via the optional MCP route | | `/blog image edit <path> <instructions>` | Edit an existing blog image (optional MCP route only) | | `/blog image setup` | Check the API key and, optionally, install the MCP server |

Blog Image Types

Match the image type to blog use case:

| Image Type | Aspect Ratio | Resolution | Domain Mode (MCP route) | Placement | |------------|-------------|-----------|-------------|-----------| | Hero/Cover | `16:9` | 2K or 4K | Editorial / Landscape | Frontmatter `coverImage` | | OG/Social Card | `16:9` | 1K | Editorial / Infographic | Frontmatter `ogImage` | | Inline Illustration | `16:9` or `4:3` | 1K | Varies by topic | After H2, before body | | Inline Product Shot | `4:3` or `1:1` | 1K | Product | Within product sections | | Section Divider | `21:9` then crop | 1K | Abstract / Landscape | Between major sections |

**Sizing requirements:**

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

Generation Routes

1. **Direct API (default).** The repo's `generate_hero.py` calls the Gemini API only when run with `--allow-paid` (after the consent gate) and `GOOGLE_AI_API_KEY` or `GEMINI_API_KEY` is set (the `google-genai` SDK must be installed), then falls back to premium stock and Openverse. It needs no MCP server. `NANOBANANA_MODEL` sets its default model ID. 2. **Optional MCP (at your own risk).** `@ycse/nanobanana-mcp@1.1.1` is the only package the setup script pins, and it only supports image model IDs that Google shut down on 2026-06-25 (see Step 2). Use it only if the user already has a working server; never present it as the default.

Before using the MCP route, check availability: call `get_image_history` with `conversation_id: "default"` (no side effects). If it fails, use the direct API route instead of asking the user to install the MCP.

When called internally (from blog-write/blog-rewrite) and no route works: no error, but return a one-line fallback note (what was skipped, why) for the caller's final summary. The calling workflow continues with stock photos.

Generation Workflow

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

Step 1: Aspect Ratio

Direct API: the script requests `16:9` and fits the result to `--width` by `--height` (default 1200x630). MCP route: call `set_aspect_ratio` BEFORE generating, with `conversation_id: "default"`.

| Blog Use Case | Ratio | |---------------|-------| | Hero / Cover / OG | `16:9` | | Product shot / Square | `4:3` or `1:1` |