models.search({ endpointIds: ['<endpoint id>'], includeOpenApi: true }), then pass them as input.
Video, audio and training runs usually take minutes. After submitting, models.run waits up to 10 seconds (at most 15). When it sees the run end within the wait, it answers a final state: SUCCEEDED with output, or FAILED with error (bad input or a model error), and there is nothing to follow. Any other answer carries the run’s response_url and IN_PROGRESS or IN_QUEUE. IN_QUEUE also covers a read that failed or ran out of time, so the run may already have started or even finished at fal. Follow every IN_QUEUE or IN_PROGRESS answer with queue.status({ responseUrl }) until it says SUCCEEDED or FAILED, or pass webhookUrl and let fal post the result. On Corsair’s cloud, get_job and the job card do the following for you.
What you get:
- 14 typed API operations
- 1 incoming webhook event types
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the fal API key before the first call: More: API Key
pnpm corsair setup --plugin=fal --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
Find text-to-video modelsWebhooks
PasswebhookUrl to queue.submit and fal POSTs the result there when the request finishes. Hand processWebhook the raw body text (await request.text()), not parsed JSON. fal signs the exact bytes it sent; a parsed body is rebuilt as a best effort, which fails for outputs with whole-number floats or integers past 2^53. To hold deliveries to one fal account, store its fal user id (the x-fal-webhook-user-id header) as the account’s user_id.
What’s next
API reference
Every
fal.api.* operation with input and output types.Webhooks
Event paths, payloads, and
webhookHooks examples.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.