ai-image-creator

# AI Image Creator Generate PNG images via multiple AI models, routed through Cloudflare AI Gateway BYOK or directly via OpenRouter/Google AI Studio. ## Model Selection When the user mentions a model keyword in their image request, use the corresponding `--model` flag: | Keyword | Model | Use When User Says | Best For (measured cost · time per image) | |---------|-------|--------------------|-------------------------------------------| | `gemini` | [Google Gemini 3.1 Flash](https://openrouter.ai/google/gemini-3.1-flash-image) | "gemini", "nano banana 2" | Previous default; still marginally closer on the Opus benchmark; up to 4K ($0.067 · 12s at 1K) | | `gemini-lite` | [Google Gemini 3.1 Flash Lite](https://openrouter.ai/google/gemini-3.1-flash-lite-image) | "gemini lite", "nano banana lite", "fast draft" | Fast cheap iteration; **1K only** ($0.034 · 5s) | | `nano-banana-2.1` | [Google Nano Banana 2.1](https://openrouter.ai/google/gemini-nano-banana-2.1) (default) | "nano banana 2.1", "nb 2.1", "generate an image" (no model specified) | Versatile default, Flash-tier successor to `gemini`: refs, `--analyze`, up to 4K; near-identical fidelity for ~44% less ($0.038 · 12s at 1K) | | `geminipro` | [Google Gemini 3 Pro](https://openrouter.ai/google/gemini-3-pro-image) | "geminipro", "gemini pro", "use gemini pro" | Highest-quality Gemini (~$0.17 at 2K) | | `riverflow` | [Sourceful Riverflow v2 Pro](https://openrouter.ai/sourceful/riverflow-v2-pro) | "riverflow", "use riverflow" | Artistic/illustration ($0.15) | | `flux2` | [FLUX.2 Max](https://openrouter.ai/black-forest-labs/flux.2-max) | "flux2", "flux", "use flux" | Illustration, clean lines (~$0.07/MP) | | `seedream` | [ByteDance Seedream 5.0 Lite](https://openrouter.ai/bytedance-seed/seedream-5-0-lite) | "seedream", "use seedream" | **2K/4K only**, web-connected knowledge, 14 refs ($0.035 · 40s at 2K) | | `gpt5.4` | [OpenAI GPT-5.4 Image 2](https://openrouter.ai/openai/gpt-5.4-image-2) | "gpt5.4", "gpt-5.4 image", "use gpt5.4" | Multimodal GPT; also `--analyze` (token-billed) | | `gpt-sunburst` | [OpenAI GPT Image 2.5 Sunburst](https://openrouter.ai/openai/gpt-image-2.5-sunburst) | "gpt image", "gpt image 2.5", "sunburst" | Precision editing, 16 refs, `--quality` up to `max`, native `-t` ($0.015 · 26s at default quality; token-billed, rises with `--quality`) | | `gpt-flare` | [OpenAI GPT Image 2.5 Flare](https://openrouter.ai/openai/gpt-image-2.5-flare) | "gpt flare", "fast gpt image" | Same features as Sunburst, speed tier ($0.015 · 19s at default quality) | | `mai` | [Microsoft MAI-Image-2.6](https://openrouter.ai/microsoft/mai-image-2.6) | "mai", "microsoft image" | Multi-reference compositing of people/products/styles, 5 refs ($0.041 · 25s) | | `mai-flash` | [Microsoft MAI-Image-2.6 Flash](https://openrouter.ai/microsoft/mai-image-2.6-flash) | "mai flash" | Faster MAI, same 5-ref editing ($0.020 · 15s) | | `grok` | [xAI Grok Imagine Image 2.0](https://openrouter.ai/x-ai/grok-imagine-image-2.0) | "grok", "grok imagine" | 1K/2K, `--quality low\|medium`, 3 refs ($0.060 · 66s — billed above its $0.04 list price; +$0.01/ref) | | `qwen` | [Qwen Image 3](https://openrouter.ai/qwen/qwen-image-3) | "qwen", "qwen image" | Small legible text (posters, UI, infographics), 1K/2K, 4 refs ($0.030 · 63s) | | `qwen-pro` | [Qwen Image 3 Pro](https://openrouter.ai/qwen/qwen-image-3-pro) | "qwen pro" | Qwen Image 3 with richer world knowledge ($0.040 · 57s) | | `muse` | [Meta Muse Image](https://openrouter.ai/meta/muse-image) | "muse", "meta image" | Complex multi-part prompts; reasons first, may search the web; prompt only ($0.010 · 18s, 1600px) | | `recraft-flash` | [Recraft V4.1 Flash](https://openrouter.ai/recraft/recraft-v4.1-flash) | "recraft", "cheapest", "quick draft" | Cheapest/fastest ~1K drafts; no `-r` ($0.007 · 5s) | Models from `seedream` down to `recraft-flash` (except `gpt5.4`) use the OpenRouter **Images API** (`/v1/images`). Each accepts only the `-a`/`-s`/`--quality`/`-r` options it supports, and the script rejects anything else before calling the API. Run `--list-models` to see each model's limits. **Cost and time** are real OpenRouter charges and end-to-end times (through the Cloudflare gateway) at default settings. They come from the Claude Opus robot benchmark, one sample per model on 2026-09-28 (`nano-banana-2.1` on 2026-10-07). `geminipro`, `riverflow`, `flux2` and `gpt5.4` were not benchmarked; their figures are list prices or earlier cost-log values. For per-model output format, resolution and quality notes, read `references/model-benchmarks.md`. Re-run the benchmark with the `ai-image-test-run` skill. ## Instructions > **Routing check:** If the user asks to **describe, analyze, or explain an existing image** (not generate a new one), skip directly to the **Image Analysis (`--analyze`)** section below. No prompt enhancement or output path needed. > > **Video routing:** If the user asks to **describe, analyze, or explain a video** (or wants a text description of a clip to seed/extend a video prompt), skip directly to the **Video Analysis (`--analyze-video`)** section below. ### Step 1: Write Prompt For long or complex prompts (recommended), write to `${CLAUDE_SKILL_DIR}/tmp/prompt.txt` using the Write tool: ``` Write prompt text to ${CLAUDE_SKILL_DIR}/tmp/prompt.txt ``` For short prompts (under 200 chars, no special characters), pass inline via `--prompt`. **CRITICAL — Prompt Quality Tips:** - Be detailed and descriptive. Include style, colors, composition, background, and intended use. - Good: "A flat-design globe icon with vertical timezone band lines in blue and teal, white background, clean vector style, suitable for a web app at 512x512 pixels" - Bad: "globe icon" - Specify "transparent background" or "white background" explicitly. - For icons, mention the target size (e.g., "512x512", "favicon at 32x32"). - For photos, describe lighting, camera angle, and mood. ### Step 1.5: Prompt Enhancement (Optional — Progressive Disclosure) Professional prompt patterns are available in 3 reference files. These are **not loaded by default** — only read them when the user's request matches a category or they explicitly ask for enhancement. **Category Detection** — Match the user's request to a category: | If request mentions... | Category | Also read | |----------------------|----------|-----------| | "product shot", "product photo", "hero image" | `product_hero` | `prompt-core.md` + `prompt-categories.md` § product_hero | | "lifestyle", "in-use", "in context" | `lifestyle` | `prompt-core.md` + `prompt-categories.md` § lifestyle | | "instagram", "social media", "tiktok", "pinterest" | `social_media` | `prompt-core.md` + `prompt-platforms.md` + `prompt-categories.md` § social_media | | "banner", "ad", "email header" | `marketing_banner` | `prompt-core.md` + `prompt-platforms.md` + `prompt-categories.md` § marketing_banner. **Routing hint:** If user has an existing logo and wants multiple standard sizes → use composite mode instead (see `## Composite Banners`). | | "website", "app", "logo", "ad format", "leaderboard", "skyscraper" | `web_app` | `prompt-core.md` + `prompt-platforms.md` + `prompt-categories.md` § web_app. **Routing hint:** For "logo banners" or "OG images with my logo" where user has existing logo → use `composite-banners.py`. For "design me a new logo" → use `generate-image.py`. | | "brand kit", "logo banners", "banner sizes", "IAB sizes", "consistent banners" + user has existing logo | `composite` | Read `references/composite-reference.md`, use `composite-banners.py` | | "icon", "favicon", "app icon" | `icon_logo` | `prompt-core.md` + `prompt-categories.md` § icon_logo | | "mascot", "character", "illustration", "artwork" | `illustration` | `prompt-core.md` + `prompt-categories.md` § illustration | | "food", "drink", "recipe", "restaurant" | `food_drink` | `prompt-core.md` + `prompt-categories.md` § food_drink | | "building", "interior", "room", "architecture" | `architecture` | `prompt-core.md` + `prompt-categories.md` § architecture | | "chart", "infographic", "data", "diagram" | `infographic` | `prompt-core.md` + `prompt-categories.md` § infographic | | "t-shirt", "mug design", "poster", "POD", "print-on-demand" | `pod_design` | `prompt-core.md` + `prompt-platforms.md` + `prompt-categories.md` § pod_design | | "consistent character", "same character/product across frames", "comic strip", "storyboard", "frame set", "start and last frame", "panels", "before/after" | `frame_consistency` | Read `references/consistency-presets.md` — keep people/objects/scenes consistent across a SET of frames (for video first/last frames or stitched comic strips) | | "describe", "analyze", "what's in this image", "explain image" | `analyze` | Handled by the top **Routing check** — read `references/analyze-reference.md` only for advanced/structured analysis patterns | | No match / simple request | — | Skip patterns, generate directly | **When to skip enhancement:** - User's prompt is already detailed (150+ words with camera/lighting/composition specifics) - Simple/direct requests ("generate a blue circle on white background") - User says "no pattern" or provides a fully formed prompt **When to apply:** - User says "use product_hero pattern" or "apply social_media pattern" (explicit) - Request clearly matches a category above (auto-detect) - User asks for "enhanced prompt" or "professional quality" **Reference files** (in `references/` directory): - `prompt-core.md` — Foundational rules: narrative prompting, camera/lens/lighting specs, text rendering rules, model recommendations - `prompt-platforms.md` — Social media ratios, IAB ad sizes, web dimensions, POD specs — all mapped to `-a`/`-s` flags - `prompt-categories.md` — 11 category formulas with templates and complete example prompts ### Step 2: Run Generation Script ```bash uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ -o "OUTPUT_PATH" \ [--provider openrouter|google] \ [-a "16:9"] \ [-s "2K"] \ [-m "model-id"] \ [-r "ref-image.png"] \ [--quality "high"] \ [-t] ``` With a specific model: ```bash uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ -o "OUTPUT_PATH" \ -m riverflow \ -p "A serene mountain lake at sunset" ``` With transparent background (requires ffmpeg + imagemagick): ```bash uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ -o "mascot.png" \ -t \ -p "A friendly robot mascot character" ``` With reference image for editing/style transfer (see **Reference Images** for which models accept `-r`): ```bash uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ -o "edited.png" \ -r "original.png" \ -p "Change the background to a sunset scene" ``` Or with inline prompt (default model): ```bash uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ -o "OUTPUT_PATH" \ -p "A simple blue circle on white background" ``` ### Step 3: Clean Up (if temp file used) ```bash rm -f ${CLAUDE_SKILL_DIR}/tmp/prompt.txt ``` ### Step 4: Verify Output ```bash file OUTPUT_PATH ```