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

Task	Model	Flag	Price
Reference-guided (i2i)	`fal-ai/nano-banana-pro/edit`	(default when refs provided)	$0.15
Text-to-image	`fal-ai/flux-2-pro`	(default when no refs)	~$0.05
Poster/Infographic (t2i)	`fal-ai/nano-banana-pro`	`--model nbp`	$0.15
Text in image	`fal-ai/ideogram/v3`	—	—

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

Backend: BytePlus Seedream

Task	Model	Flag	Price
Text-to-image	`seedream-4-5-251128`	`--model seedream`	$0.03
Reference-guided (i2i)	`seedream-4-5-251128`	`--model seedream --refs ...`	$0.03

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

Model Aliases

Alias	Routes to
`seedream`, `byteplus`, `sd`	BytePlus Seedream
`nbp`, `nano-banana-pro`, `poster`	fal.ai NBP t2i
`flux`, `flux-2-pro`	fal.ai Flux

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

Platform	Ratio	Notes
Xiaohongshu / Stories	9:16	Vertical full-screen
Instagram Feed (2026)	3:4	New optimal — taller than 4:5, more screen real estate
Instagram Feed (legacy)	4:5	Still supported, less tall
Instagram Carousel	3:4	Mixed carousels = highest engagement (2.33%)
Banner / Website	16:9	Landscape
Square	1:1	Generic / WeChat Moments
Poster (default)	3:4	Best for designed travel posters

Limits

Backend	Max refs	Speed	Cost
BytePlus Seedream	14	~15-40s	$0.03/img
fal.ai NBP	4	~15-25s	$0.15/img
fal.ai Flux	0	~5-10s	~$0.05/img

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):

Tier	Pixels (4:5)	Total	Best For
`standard`	1920x2400	~4.6M	Social media, fast generation
`high` (default)	2560x3200	~8M	Download, zoom, high quality
`max`	3200x4000	~12.8M	Print, ultra-high quality

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

phy-fal-image-gen

Installation