FAL Image Gen

Generate images via fal.ai and BytePlus Seedream APIs. Supports single image, batch parallel, and reference-guided generation. Use when you need to generate...

Security Scan

The SKILL.md describes a coherent image-generation workflow (fal.ai and BytePlus Seedream) but the package metadata and manifest are inconsistent: it declares no required env/binaries or code while the instructions expect API keys, a local Python script, and a runnable 'uv' command — this mismatch is suspicious and needs clarification before use.

Purpose & Capability

The skill's stated purpose (image generation via fal.ai and BytePlus Seedream) matches the instructions, but the registry metadata lists no required environment variables, binaries, or code files while SKILL.md clearly expects FAL_API_KEY and BYTEPLUS_API_KEY and a local script at {baseDir}/skills/fal-image-gen/scripts/generate.py. The absence of declared credentials/code in the manifest is incoherent.

Instruction Scope

SKILL.md instructs the agent to run a local Python script with 'uv run' against paths under {baseDir}, accept external reference image URLs, and auto-upload BytePlus URLs to fal.ai storage. But no script or upload code is included in the package. The instructions require network I/O (fetching refs, calling external APIs) and local filesystem reads/writes that are not represented in the manifest.

Install Mechanism

There is no install spec (instruction-only), which is low risk in itself. However, the runtime instructions implicitly require a Python runtime, an executable invoked as 'uv', and a generate.py script — none of which are declared or provided. That mismatch raises operational concerns but not direct install-supply risk from this package.

Credentials

The SKILL.md reasonably requires FAL_API_KEY and BYTEPLUS_API_KEY (proportionate to contacting those services). However, the package registry metadata did not list those required env vars or a primary credential, creating an inconsistency that should be resolved before trusting the skill.

Persistence & Privilege

The skill does not request elevated persistence: always is false, no system config paths are requested, and there is no install-time modification described. Autonomous invocation is allowed (default), which is normal and not by itself a red flag.

What to consider before installing

This skill's description and SKILL.md describe a plausible image-generation tool, but the bundle is incomplete and inconsistent. Before installing or supplying API keys: 1) Ask the publisher for the missing generate.py and any helper code, and verify they match the SKILL.md behavior. 2) Confirm which binaries are required (what 'uv' refers to) and whether any other packages are needed. 3) Only provide FAL_API_KEY and BYTEPLUS_API_KEY if you trust the code and know how keys are stored/used; keys will be used to call external APIs and could be logged or uploaded if the script is malicious. 4) Verify privacy: reference-image URLs will be fetched and (per SKILL.md) uploaded to fal.ai storage for permanent URLs—make sure that is acceptable for any sensitive images. 5) If you cannot obtain the missing code, treat this package as incomplete and avoid running arbitrary commands it suggests. If you want, request the skill author to publish a complete package manifest (list required env vars, required binaries, provide the generate.py, and add an install spec) before use.

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