FAL.ai model catalog access — image, video, audio, 3D, LoRA training, and more via fal-ai/ and bytedance/ and wan/ endpoints. Activate when the user configures any nebula node that routes through FAL (kling, sora, veo, flux, seedance, wan, luma, pixverse, ltx, moonvalley, hunyuan3d, recraft, nano-banana via FAL, and 30+ others), when the user mentions a fal-ai/ slug, or when they ask which FAL model to use for a task. Entry point for 160 curated per-model skills + category overviews at `.agents/skills/fal/`.
FAL.ai model catalog access — image, video, audio, 3D, LoRA training, and more via fal-ai/ and bytedance/ and wan/ endpoints. Activate when the user configures any nebula node that routes through FAL (kling, sora, veo, flux, seedance, wan, luma, pixverse, ltx, moonvalley, hunyuan3d, recraft, nano-banana via FAL, and 30+ others), when the user mentions a fal-ai/ slug, or when they ask which FAL model to use for a task. Entry point for 160 curated per-model skills + category overviews at `.agents/skills/fal/`.
FAL Skill
When to use
User configures any FAL-backed nebula node (see the full mapping below)
User asks "which FAL model for X" or mentions a specific fal-ai/* or bytedance/* or wan/* slug
User asks about FAL pricing, rate limits, or endpoint schemas
Codex is building a graph with a FAL-backed node and needs exact parameter names and valid ranges
Universal FAL conventions
All FAL endpoints (there are 1,312+ models on the platform, 160 curated here) share the same API shape:
Auth:Authorization: Key <FAL_KEY> header. Our backend uses FAL_KEY. Some models also accept native-provider keys (e.g. BFL_API_KEY for Flux, GOOGLE_API_KEY for Veo) — nebula handlers prefer native when set, fall back to FAL.
Two base URLs:https://fal.run/{endpoint_id} (sync, for fast models) and https://queue.fal.run/{endpoint_id} (queue, for slow/long-running models). Nebula's fal_universal.py handler uses queue for everything since most models benefit from async.
Queue flow:
POST https://queue.fal.run/{endpoint_id} with JSON body → returns {"request_id": "...", "status_url": "...", "response_url": "..."}
Poll GET {status_url} until "status": "COMPLETED" (states: IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED)
GET {response_url} to fetch the result
Standard status codes:200 (sync success or poll OK) · 401 (bad key) · 402 (insufficient credit) · 422 (invalid params) · 429 (rate limit).
Output shape varies by model type but follows conventions:
3D mesh: {"model_glb": {"url": "..."}} or {"model_mesh": {"url": "..."}}
URL tokens expire. Response URLs include signed ?Expires= params. Download promptly.
Nebula node → FAL endpoint map
The source of truth for this routing is backend/execution/sync_runner.py. Each nebula node id on the left is implemented as a FAL-universal wrapper that defaults endpoint_id to the slug on the right.
Routing note: Some nebula nodes have two handlers (direct + FAL) with a routing param selecting which. The dual-param convention (sharedParams, falParams, directParams) comes from that — falParams only apply when routed through FAL.
How to use this skill
When the user configures or builds with a FAL-backed node:
Find the endpoint in the table above.
Open the matching skill file in skills/ for that model.
Use its Input parameters section as the source of truth for valid params, defaults, and ranges.
Use its When to use / Don't use / Alternatives section to decide if it's the right model.
Use its Prompting best practices section (most skills have one) to craft the input.
When the user asks about a FAL model not in the table above:
Check skills/fal-ai__*.md for a direct file matching the slug (file naming: fal-ai__ prefix, __ for /, .md suffix — so fal-ai/foo/bar → fal-ai__foo__bar.md).
If no file exists, fetch live: https://fal.ai/models/{slug}/llms.txt via WebFetch. That's FAL's LLM-friendly spec.
Mention to the user that this model isn't currently a curated nebula node — they can use fal-universal with the slug.
Category overviews
Browse all 160 skills by category: categories/{category}.md. Categories available:
FAL doesn't publish public rate-limit numbers. Empirically:
Sync endpoints (fal.run/...) are usage-billed per-request, often with per-second rate limits documented per model.
Queue endpoints handle bursts but a single request still blocks on queue position.
Each model's skill file has a Pricing section with exact $/image, $/second-of-video, or $/credit figures.
Universal prompting guidance
The bundle's skill files each have a "Prompting best practices" section. High-leverage universal patterns across FAL models:
Narrative > keyword soup — full prose descriptions beat comma-separated tags on every FAL image model (Flux, Nano Banana, Imagen, Recraft, Seedream, Ideogram).
Quote dialogue in video prompts — Veo, Sora 2, Kling all parse quoted strings as speech. SFX as plain text.
Specify camera terms explicitly — "dolly," "pan," "POV," "tracking shot," "extreme close-up" work across Veo 3.1, Kling v3, Seedance 2.
Put reference images first in multi-image prompts — most models prioritize the first reference.
Seeds are reproducibility, not style-transfer — fixing a seed preserves a generation, not a style. For style transfer use model-specific image_prompt or reference_image_urls params.
Source note + staleness
Bundle copied into this repo from the project reference docs on 2026-04-17.
Master bundle has a sync_fal_models.py script that can refresh skills against FAL's live API (uses fal.ai/api/models + per-model llms.txt + OpenAPI). Re-run it in the vault when you want fresh data, then re-copy into this project.
For any specific parameter that feels stale, fetch https://fal.ai/models/{slug}/llms.txt to verify — that's the canonical LLM-friendly source.
