ai-image-creator

name ai-image-creator description Generate, edit-from-reference, or analyze images with AI via OpenRouter (gemini, geminipro, riverflow, flux2, seedream, gpt5, gpt5.4; Cloudflare AI Gateway BYOK). Also analyze a video (--analyze-video, read-only — no video generated) into a text description for video prompts. Use when the user asks to generate an image, create a PNG, make an icon, make it transparent, edit with a reference, design a logo/banner, describe/analyze/explain an image ("what's in this image"), or describe/analyze a video ("what happens in this video"). allowed-tools Bash, Read, Write compatibility Requires uv (Python runner) and network access. Environment variables for CF AI Gateway or direct API keys must be configured in shell profile (~/.zshrc on macOS, ~/.bashrc on Linux, or System Environment Variables on Windows). metadata {"tags":"image-generation, ai, openrouter, cloudflare, gemini, flux2, riverflow, seedream, gpt5, gpt54"} 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 gemini Google Gemini 3.1 Flash (default) "gemini", "generate an image" (no model specified) geminipro Google Gemini 3 Pro "geminipro", "gemini pro", "use gemini pro" riverflow Sourceful Riverflow v2 Pro "riverflow", "use riverflow" flux2 FLUX.2 Max "flux2", "flux", "use flux" seedream ByteDance SeedDream 4.5 "seedream", "use seedream" gpt5 OpenAI GPT-5 Image "gpt5", "gpt5 image", "use gpt5" gpt5.4 OpenAI GPT-5.4 Image 2 "gpt5.4", "gpt-5.4 image", "use gpt5.4" 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 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" ] \ [-t] With a specific model: 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): 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 (multimodal models only): 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): 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) rm -f ${CLAUDE_SKILL_DIR} /tmp/prompt.txt Step 4: Verify Output file OUTPUT_PATH Confirm it shows "PNG image data" and report the file path and size to the user. Step 5: Post-Processing (optional) If the user needs resizing, format conversion, or other manipulation, first detect available image tools, then use them. See Image Tools section below. Parameters Argument Short Required Default Description --output -o Yes -- Output file path (parent dirs auto-created) --prompt -p No -- Inline prompt text --prompt-file -- No ../tmp/prompt.txt Path to prompt file --provider -- No openrouter openrouter or google --aspect-ratio -a No model default OpenRouter only: 1:1 , 16:9 , 9:16 , 3:2 , 2:3 , 4:3 , 3:4 , 4:5 , 5:4 , 21:9 --image-size -s No model default OpenRouter only: 1K , 2K , 4K . 0.5K is accepted only on the Gemini 3.1 Flash preview build ( -m google/gemini-3.1-flash-image-preview-20260226 ); every selectable keyword rejects it --model -m No gemini Model keyword ( gemini , geminipro , riverflow , flux2 , seedream , gpt5 , gpt5.4 ) or full model ID --ref -r No -- Reference image file (repeatable). For editing/style transfer. Multimodal models only (gemini, geminipro, gpt5, gpt5.4) --analyze -- No -- Analyze/describe a reference image (text-only output, no image generated). Requires -r . Multimodal models only --analyze-video -- No -- Analyze/describe a video. Pass the video via -r (local file or URL). OpenRouter only. Choose a model/preset with -m (default gemini3.5-flash ). Returns structured JSON by default --prose -- No -- ( --analyze-video only) Return free-text prose instead of the default structured JSON --contact-sheet -- No -- ( --analyze-video , local file only) Extract evenly-spaced keyframes with ffmpeg and save a labeled contact-sheet image to PATH — a human ground-truth reference. Skipped for URL sources / if ffmpeg is missing --verify -- No -- ( --analyze-video , local file only) Second pass that checks the analysis against extracted frames (no video re-sent) and classifies each claim supported / contradicted / not_visible . Adds a verification object. Costs one extra model call --transparent -t No -- Generate with transparent background. Requires ffmpeg + imagemagick --costs -- No -- Display generation/cost history for this project and exit --list-models -- No -- List available model keywords and exit Environment Variables Variable Required For Description AI_IMG_CREATOR_CF_ACCOUNT_ID Gateway mode Cloudflare account ID AI_IMG_CREATOR_CF_GATEWAY_ID Gateway mode AI Gateway name AI_IMG_CREATOR_CF_TOKEN Gateway mode Gateway auth token