FAL Image Generation#

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

Environment Variables#

bash

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#

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

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

Backend: BytePlus Seedream#

TaskModelFlagPriceText-to-imageseedream-4-5-251128``--model seedream$0.03Reference-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#

AliasRoutes toseedream, byteplus, sdBytePlus Seedreamnbp, nano-banana-pro, posterfal.ai NBP t2iflux, flux-2-profal.ai Flux

Auto-Selection Logic#

text

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#

bash

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#

bash

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#

bash

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#

bash

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

bash

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

bash

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

JSON format for batch (mix models freely):

json

[
  {"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#

PlatformRatioNotesXiaohongshu / Stories9:16Vertical full-screenInstagram Feed (2026)3:4New optimal — taller than 4:5, more screen real estateInstagram Feed (legacy)4:5Still supported, less tallInstagram Carousel3:4Mixed carousels = highest engagement (2.33%)Banner / Website16:9LandscapeSquare1:1Generic / WeChat MomentsPoster (default)3:4Best for designed travel posters

Limits#

BackendMax refsSpeedCostBytePlus Seedream****1415-40s**$0.03/img**fal.ai NBP415-25s$0.15/imgfal.ai Flux05-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):

TierPixels (4:5)TotalBest Forstandard1920x24004.6MSocial media, fast generationhigh (default)2560x32008MDownload, zoom, high qualitymax3200x4000~12.8MPrint, ultra-high quality

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

bash

# 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

---

Author#

Canlah AI — Run performance marketing without breaking your brand.

• GitHub: github.com/PHY041
• All Skills: clawhub.ai/PHY041