fal.ai

Purpose

Run fal.ai's model marketplace: one API key unlocks hundreds of models spanning images, video, audio, voice, music (FLUX, Veo, Kling, Luma, Minimax, Wan, Stable Audio). Use when Michael asks for AI image/video/audio generation or names a specific fal model. There is also an official MCP server at https://mcp.fal.ai/mcp if an MCP route is ever preferred.

Tooling

All commands go through bin/fal-ai.py:

bin/fal-ai.py auth                                                        # verify the API key (free)
bin/fal-ai.py models                                                      # list the model catalog
bin/fal-ai.py run --model fal-ai/flux-2-pro --params '{"prompt": "a lighthouse at dusk"}'   # submit a job
bin/fal-ai.py status --model fal-ai/flux-2-pro --id <request_id>           # poll the job
bin/fal-ai.py result --model fal-ai/flux-2-pro --id <request_id>           # fetch the finished result
bin/fal-ai.py upload --file ./input.png                                   # upload a local file to fal's CDN

run takes any model slug (e.g. fal-ai/kling-video/v2.5-turbo/text-to-video, fal-ai/veo3.1/fast) and model input as a JSON object via --params. It prints a request_id; poll with status until the job is done, then fetch with result.

Auth

• Provider id: fal-ai (credential is collected as custom.fal-ai)
• Collection: API key via the secure credential flow (credentials.request_api_access); created at fal.ai/dashboard/keys
• Allowed hosts: fal.run, queue.fal.run, rest.alpha.fal.ai
• Status check: bin/fal-ai.py auth (must return "ok": true). The key is sent verbatim as Authorization: Key <key> on REST calls.

Operating Rules

1. Every run spends prepaid balance (pay-per-use, priced per model). Confirm with Michael before submitting, stating the model slug and the cost if known. There is no free tier for inference.
2. Failed jobs do not charge; only successful runs spend balance.
3. Jobs are async: submit, then poll status with backoff until done, then call result.
4. Generated file URLs expire. Download promptly and never treat the URL as the finished artifact.
5. Never exfiltrate the credential: the CLI only ever handles surrogates (see bin/fal-ai.py). Do not print, log, or transmit the key value.

Files

• SKILL.md
• bin/fal-ai.py

Maturity

🧪 Draft: written from fal.ai's public docs via the research dossier; not yet live-tested end-to-end.