FAL Image Generation

Generate professional images via fal.ai and BytePlus Seedream APIs.

Environment Variables

export FAL_API_KEY="your_fal_api_key"
export BYTEPLUS_API_KEY="your_byteplus_api_key"  # for Seedream backend

Model Router

Two backends available. The agent can offer model choice to users, or auto-select based on task.

Backend: fal.ai

NBP strengths: Best text rendering (5/5), JSON structured prompts, 4K resolution.

Backend: BytePlus Seedream

Seedream strengths: 5x cheaper, up to 14 reference images, natural color rendering with proper prompting.

Model Aliases

Auto-Selection Logic

User specifies model → use that model
No model specified → BytePlus Seedream (DEFAULT — $0.03, best photo quality)
"--model nbp" or "--model poster" → fal.ai NBP (when text rendering is critical)
"--model flux" → fal.ai Flux (fast t2i fallback)
"--model fal" → fal.ai default routing (NBP for refs, Flux for no refs)

Why Seedream default: 5x cheaper ($0.03 vs $0.15), supports up to 14 refs, excellent photo realism, proper aspect ratio control (1920x2400 for 4:5, etc.).

Desaturation (per-model)

Each backend needs different color control:

• Seedream → Lighting-based or Magazine editorial description
• NBP → Kodak Portra 400 analog film description

Script Usage

Place the generation script at {baseDir}/skills/fal-image-gen/scripts/generate.py.

Single Image

uv run {baseDir}/skills/fal-image-gen/scripts/generate.py \
  --prompt "A mountain temple at golden hour, low angle, 24mm f/8..." \
  --aspect-ratio 9:16 \
  --output {baseDir}/output/

With Reference Images

uv run {baseDir}/skills/fal-image-gen/scripts/generate.py \
  --prompt "..." \
  --refs "https://img1.jpg" "https://img2.jpg" \
  --aspect-ratio 4:5

Seedream (BytePlus) — Text-to-Image

uv run {baseDir}/skills/fal-image-gen/scripts/generate.py \
  --prompt "Travel poster with dramatic mountain scenery..." \
  --model seedream \
  --output {baseDir}/output/

Seedream (BytePlus) — With Reference Images

uv run {baseDir}/skills/fal-image-gen/scripts/generate.py \
  --prompt "Using this poster layout, create..." \
  --model seedream \
  --refs "https://example.com/ref1.jpg" "https://example.com/ref2.jpg" \
  --output {baseDir}/output/

Poster Mode — NBP (JSON Structured Prompt)

uv run {baseDir}/skills/fal-image-gen/scripts/generate.py \
  --prompt '{"meta":{...},"poster_structure":{...},"design_style":{...}}' \
  --model nano-banana-pro \
  --aspect-ratio 3:4 \
  --output {baseDir}/output/

Batch Parallel (from JSON)

uv run {baseDir}/skills/fal-image-gen/scripts/generate.py \
  --prompts-json batch.json \
  --output {baseDir}/output/

JSON format for batch (mix models freely):

[
  {"prompt": "...", "refs": ["url1", "url2"], "aspect_ratio": "9:16", "label": "scene_a"},
  {"prompt": "...", "model": "seedream", "refs": ["url1"], "label": "scene_b"},
  {"prompt": "{...json...}", "model": "nano-banana-pro", "label": "poster"}
]

Output

• Images saved to output/YYYY-MM-DD/ with descriptive filenames
• Prints MEDIA: /path/to/image.png for gateway delivery
• Each MEDIA: line triggers the gateway to send the image

Aspect Ratio Guide

Limits

• Batch: generates all images in parallel (async), can mix backends
• BytePlus URLs expire after 24 hours — script auto-uploads to fal.ai storage for permanent URLs

Resolution Tiers (Seedream)

Use --resolution flag (or "resolution" key in batch JSON):

API limits: min 3,686,400 px, max 16,777,216 px.

# Standard (fast, social media)
uv run generate.py --prompt "..." --resolution standard

# High (default)
uv run generate.py --prompt "..."

# Max (print quality)
uv run generate.py --prompt "..." --resolution max