generate-image

name	generate-image
description	Generate AI images using FAL AI (Seedream 4, Flux 2), Gemini, OpenAI, or Grok (xAI). Use for blog covers, newsfeed visuals, marketing content, cinematic keyframes, or any image generation needs. Seedream 4 is the default for cinematic/creative marketing work — it beats Flux 2 on composition, photorealism, and scene complexity.
allowed-tools	Bash, Read, Write
env	FAL_KEY | GEMINI_API_KEY | OPENAI_API_KEY | XAI_API_KEY

AI Image Generation

Generate high-quality AI images for blog posts and marketing content.

Model selection (pick by use-case, not by habit)

Need	Use	Why
Cinematic marketing, video keyframes, premium scene	Seedream 4.5 (default)	Newest stable. $0.04/piece PAYG, 200 free pieces on ModelArk account.
Cost-conscious bulk (blog covers, variants)	Seedream 4.0 (--model seedream-4-0-250828)	$0.03/piece — 25% cheaper than 4.5. 200 free pieces on ModelArk.
Top-tier hero shot, willing to pay	Seedream 5.0 (--model seedream-5-0-260128)	Highest fidelity. Token-priced (not per-piece), more expensive. Reserve for hero shots.
Seedream 5.0-Lite	Not on public API	Visible in ModelArk UI ($0.035/pc, 50 free) but not in /api/v3/models list. Use UI-side generation if needed.
Blog cover with AI/tech motifs	Flux 2 (generate-image.ts)	Good at abstract visuals, fast
Photorealistic UGC / lifestyle	Grok Image Pro (generate-image-grok.ts)	Social-feel authenticity
Fast iteration, brainstorm	Gemini (generate-image-gemini.ts)	Cheapest + fastest
Logo / icon variations	OpenAI (generate-image-openai.ts)	Clean vector-feel output

Default for cinematic video keyframes: Seedream 4. Proven 2026-04-18 on TeamDay NYC office video — produced substantially more cinematic output than Flux 2 at the same 16:9 aspect and with the same prompt.

Seedream 4.0 quick start

# 16:9 cinematic, 2K quality
python3 .claude/skills/generate-image/scripts/generate-image-seedream.py \
  "cinematic night shot of Manhattan skyline, glowing amber tower..." \
  --out scene1.png --aspect 16:9 --size auto_2K

# Portrait 9:16 for social
python3 .claude/skills/generate-image/scripts/generate-image-seedream.py \
  "prompt" --out pic.png --aspect 9:16 --size auto_2K

# Multiple variants (great for exploring a concept)
python3 .claude/skills/generate-image/scripts/generate-image-seedream.py \
  "prompt" --out explore.png --n 4

Valid --aspect: 1:1 16:9 9:16 4:3 3:4 21:9 Valid --size: square_hd square portrait_4_3 portrait_16_9 landscape_4_3 landscape_16_9 auto auto_2K auto_4K (default auto_2K)

Quick Start

Generate a blog cover image:

# FAL AI (primary - recommended)
bun .claude/skills/blog-image-generation/scripts/generate-image.ts "your detailed prompt" output-name.webp

# Gemini (fast - default 16:9)
bun .claude/skills/blog-image-generation/scripts/generate-image-gemini.ts "your detailed prompt" output-name.webp

# Gemini with custom aspect ratio
bun .claude/skills/blog-image-generation/scripts/generate-image-gemini.ts "your prompt" output-name.webp --aspect=1:1

# Gemini Pro (4K resolution)
bun .claude/skills/blog-image-generation/scripts/generate-image-gemini.ts "your prompt" output-name.webp --pro --size=4K

# OpenAI (GPT Image 1.5)
bun .claude/skills/blog-image-generation/scripts/generate-image-openai.ts "your detailed prompt" output-name.webp

# OpenAI with variations (e.g., logo options)
bun .claude/skills/blog-image-generation/scripts/generate-image-openai.ts "Logo for coffee shop" logo.webp --n=4 --size=1024x1024

# OpenAI fast iteration
bun .claude/skills/blog-image-generation/scripts/generate-image-openai.ts "Product mockup" mockup.webp --quality=low

# Grok (xAI - affordable, fast)
bun .claude/skills/generate-image/scripts/generate-image-grok.ts "your prompt" output-name.webp

# Grok Pro (higher quality)
bun .claude/skills/generate-image/scripts/generate-image-grok.ts "your prompt" output-name.webp --pro

# Grok with variations
bun .claude/skills/generate-image/scripts/generate-image-grok.ts "Logo concept" logo.webp --n=4 --aspect=1:1

Images save to: packages/marketing/public/images/

Use in blog markdown:

image: /images/output-name.webp
cover: /images/output-name.webp

When to Use

• Creating cover images for blog posts
• Generating illustrations for articles
• Visual metaphors for abstract concepts
• Marketing visuals for social media

Crafting Effective Prompts

Structure

[Subject] + [Style] + [Mood/Lighting] + [Composition]

Examples

AI/Tech Posts:

"Conceptual illustration of large and small neural networks connecting and collaborating,
glowing blue and orange data streams between them, modern tech aesthetic,
professional lighting, represents AI memory and learning"

Business Posts:

"Minimalist illustration of business growth and collaboration, geometric shapes
connecting upward, professional color palette of blues and greens, clean modern style"

Tutorial Posts:

"Isometric 3D illustration showing step-by-step workflow, bright vibrant colors,
clean lines, educational infographic style, soft shadows and professional lighting"

Prompt Tips

✅ Do:

• Be specific about style: "modern minimalist", "3D render", "conceptual illustration"
• Mention lighting: "soft professional lighting", "glowing tones", "dramatic backlight"
• Describe mood: "collaborative", "innovative", "calm and focused"
• Specify composition: "centered", "two elements connecting", "abstract visualization"
• Add constraints: "no watermark", "no text", "no logos", "plain background"

❌ Avoid:

• Vague descriptions: "nice image", "cool picture"
• Too many conflicting styles
• Overly complex scenes with many elements

Advanced Prompting (gpt-image-1.5)

Structure order: background/scene → subject → key details → constraints

For photorealism: Use camera terms (lens, aperture, lighting) rather than generic "8K/ultra-detailed"

"Shot with 50mm lens, shallow depth of field, soft natural lighting, subtle film grain"

For text in images: Put text in quotes, specify typography

"Include the text 'HELLO WORLD' in bold sans-serif, centered, white on dark background"

For logos: Request multiple variations with --n=4

"Original logo for 'Field & Flour' bakery. Clean vector-like shapes, balanced negative space,
scalable at small and large sizes. Flat design, no gradients. Plain background."

For infographics: Set --quality=high, describe layout explicitly

"Detailed infographic explaining how coffee machines work. Show: bean basket → grinder →
boiler → brew head. Technical diagram style, clear labels, professional look."

Iterate, don't overload: Start simple, then refine with follow-ups:

• "make lighting warmer"
• "remove the background element"
• "change to portrait orientation"

Available Generators

Primary: FAL AI (Recommended)

• Speed: ~30 seconds
• Quality: High (Flux 2 Flex model)
• Format: Landscape 16:9, PNG output
• Features: Automatic prompt expansion
• Script: scripts/generate-image.ts

Alternative: Gemini (Google AI)

• Models (--model=MODEL or --pro):
  • gemini-3.1-flash-image-preview (default) - Nano Banana 2, fast, Google Search grounding, 512px-4K
  • gemini-3-pro-image-preview (--pro) - Nano Banana Pro, thinking mode, up to 4K
  • gemini-2.5-flash-image - Nano Banana v1 (legacy, still available)
• Also on FAL AI: fal-ai/nano-banana-2 — same model via FAL's infrastructure
• Options:
  • --aspect=RATIO - 1:1, 16:9 (default), 9:16, 3:2, 2:3, 4:3, 3:4, 4:5, 5:4, 21:9, 1:4, 1:8, 4:1, 8:1
  • --size=SIZE - 512px, 1K, 2K (default), 4K
• Features: Text rendering, Google Search grounding (real-world landmarks/objects), subject consistency, multi-turn editing
• Script: scripts/generate-image-gemini.ts
• Requires: GEMINI_API_KEY or GOOGLE_API_KEY environment variable

Alternative: OpenAI (GPT Image 1.5)

• Model: gpt-image-1.5 (state-of-the-art photorealism, text rendering)
• Options:
  • --quality=QUALITY - low (fast), medium, high (default), auto
  • --size=SIZE - 1024x1024, 1536x1024 (default), 1024x1536, auto
  • --n=COUNT - Generate 1-10 variations (default: 1)
• Strengths: Photorealism, text in images, infographics, logos, identity preservation
• Script: scripts/generate-image-openai.ts
• Requires: OPENAI_API_KEY environment variable

Alternative: Grok (xAI)

• Models (--model=MODEL or --pro):
  • grok-imagine-image (default) - Fast, affordable ($0.02/image)
  • grok-imagine-image-pro (--pro) - Higher quality ($0.07/image)
• Options:
  • --aspect=RATIO - 1:1, 16:9 (default), 9:16, 4:3, 3:4
  • --resolution=RES - 1k (default), 2k
  • --n=COUNT - Generate 1-10 variations (default: 1)
• Strengths: Very affordable, fast generation, good creative/stylistic output
• Script: scripts/generate-image-grok.ts
• Requires: XAI_API_KEY environment variable

Instructions

Step 1: Analyze Blog Content

1. Read the blog post or outline
2. Identify the core concept or theme
3. Determine visual metaphor or illustration style

Step 2: Craft Detailed Prompt

1. Choose style (conceptual, 3D, minimalist, etc.)
2. Describe main elements (2-3 max)
3. Add mood/lighting descriptors
4. Specify composition

Step 3: Generate Image

bun .claude/skills/blog-image-generation/scripts/generate-image.ts "prompt" filename.webp

Step 4: Add to Blog Frontmatter

---
title: "Your Blog Title"
image: /images/filename.webp
cover: /images/filename.webp
---

Examples from Production

Buddy Memory Blog

Prompt:

"Conceptual illustration of large and small neural networks connecting and
collaborating, glowing blue and orange data streams between them, modern tech
aesthetic, professional lighting, represents AI memory and learning"

Output: buddy-memory.webp Used in: "Building Buddy: When Claude Built His Own Memory"

Gotchas

• NSFW content filters — All models reject prompts with violent, sexual, or harmful content. Gemini is strictest; Grok is most permissive.
• FAL AI queue times — During peak hours, Flux 2 can take 2-3 minutes instead of 30 seconds. The script will wait; don't kill it early.
• Gemini fails silently on some prompts — Returns empty response instead of an error. If you get no image, simplify the prompt or try a different model.
• OpenAI costs add up fast — --quality=high with --n=4 generates 4 high-res images at ~$0.17 each = $0.68 per batch. Use --quality=low for iteration.
• WebP conversion — All scripts output .webp. If you need PNG/JPEG, use ffmpeg or imagemagick after generation.
• Script path inconsistency — FAL/Gemini/OpenAI scripts are in .claude/skills/blog-image-generation/scripts/, but Grok is in .claude/skills/generate-image/scripts/. Use the paths shown in Quick Start.

Troubleshooting

Image Generation Fails

• Check that bun is installed: bun --version
• Verify script path is correct
• Check API keys are configured

Poor Quality Output

• Make prompt more specific and detailed
• Add style descriptors: "high quality", "professional", "detailed"
• Specify lighting conditions
• Use reference styles: "like a tech conference poster", "similar to Stripe's marketing"

Wrong Aspect Ratio

• FAL AI script uses landscape_16_9 by default (perfect for blog covers)
• Don't try to specify different ratios - it's optimized for headers

Technical Details

Output Location: packages/marketing/public/images/ Format: WebP (optimized for web) Dimensions: 16:9 landscape (1456×816px typical) File Naming: Use kebab-case: my-blog-cover.webp

Script Reference

All scripts located in: .claude/skills/blog-image-generation/scripts/

• generate-image.ts - FAL AI (primary)
• generate-image-gemini.ts - Gemini (fast or pro with --pro flag)
• generate-image-openai.ts - OpenAI GPT Image 1.5
• generate-image-grok.ts - Grok xAI (affordable, fast, --pro for higher quality)

See script files for API configuration and advanced options.