Fal AI Agent Skill

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

• 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.
• Failed jobs do not charge; only successful runs spend balance.
• Jobs are async: submit, then poll status with backoff until done, then call result.
• Generated file URLs expire. Download promptly and never treat the URL as the finished artifact.
• 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.