fal

A fal connection reaches https://queue.fal.run, fal.ai's asynchronous queue for serverless model inference. You submit a job to a model, get a request_id back straight away, then poll its status and collect the result when it finishes. That split is the whole point of this connector: polling and fetching are cheap reads an agent can do freely, while submitting is the step that spends money, so it starts switched off and asks a human every time.

What you need

A fal API key. That is a static credential, so this connector works end to end today: you paste the key once and the gateway seals it.

1. Open fal.ai/dashboard/keys and choose to create a key.
2. Choose the API scope, not ADMIN. API scope grants access to every model on fal, which is all this connection needs. ADMIN additionally grants private models, CLI operations and the admin-scoped platform APIs, none of which are reachable here.
3. Copy the key. fal shows it once.

The key is a single opaque string that fal sends as Authorization: Key <your-key>. Paste it exactly as fal gave it to you, with no Key prefix of your own — Permaura adds that.

Add the connection

In the console, open Access → Connections → Add connection and pick fal from the catalog. Paste the API key when the form asks for the credential. It is sealed on your gateway at that moment and never displayed again, and from then on Permaura injects it server-side on each approved call.

Adding the connection makes these actions possible, not permitted. An agent cannot touch any of them until a grant allows it.

What the agent can do

Capabilities are namespaced under the connection id, so an agent sees queue.status as <connection>.queue.status.

Every action that names a model takes it apart into path segments, because a segment cannot contain a slash. A two-part id like fal-ai/nano-banana is owner = fal-ai, model = nano-banana. A three-part id like fal-ai/flux/dev adds variant = dev. Only queue.submit has a _variant form, because submitting is the one route that takes the full id.

Action	What it does	On by default
queue.status	Polls a request against a two-part model id; logs=1 includes the runner's logs	Yes
queue.result	Fetches a finished request's result, two-part model id	Yes
queue.submit	Submits a job to a two-part model id	No, and it asks for approval
queue.submit_variant	Submits a job to a three-part model id	No, and it asks for approval
image.generate	Generates an image with FLUX.1 [dev], pinned to that model	No, and it asks for approval
image.generate_fast	Generates an image with FLUX.1 [schnell], pinned to that model	No, and it asks for approval
queue.cancel	Cancels a request against a two-part model id	No

Every submit spends real credit against your fal balance, and a running job burns GPU time whether or not anyone wanted it. That is why all four stay off until you switch them on, and prompt you every time even then.

If you only want an agent to make pictures, enable image.generate_fast with queue.status and queue.result, and leave the two generic submits off. The pinned actions target one model each, so the agent chooses the prompt and nothing else — no way to point the same budget at a far more expensive video model.

Good to know

• The host is pinned. Every call goes to queue.fal.run and nowhere else, whatever an agent asks for.
• Poll at the first two segments, whatever you submitted to. fal's queue keeps only owner/model on its status, result and cancel routes, even when you submitted to a three-part id: a job sent to fal-ai/flux/dev is polled at fal-ai/flux/requests/<request_id>/status, not fal-ai/flux/dev/requests/.... So queue.status, queue.result and queue.cancel are the only forms, and you give them owner = fal-ai, model = flux. The connector previously offered _variant forms of all three on the assumption that these routes repeated the full id; fal answers 405 to those, so they have been removed.
• Four-part model ids are out of scope. A few fal endpoints go a level deeper, such as fal-ai/flux/dev/image-to-image. This connector stops at three segments, so those models are not reachable through it.
• Only the listed inputs reach fal. The generic submits forward prompt, negative_prompt, image_url, image_size, num_images, num_inference_steps, guidance_scale, seed and output_format; the pinned image actions forward the same list minus negative_prompt and image_url, which FLUX does not accept. Anything else an agent sends is dropped before the request leaves your gateway. If a model you want needs a field outside that list, that model is not a good fit for this connector yet.
• The safety checker cannot be turned off. fal's image models take an enable_safety_checker input that defaults to on. It is deliberately not forwarded, so an agent cannot switch the content filter off on a call you approved for something else.
• Webhooks are not forwarded. fal's queue accepts a fal_webhook URL that it posts the result to. This connector does not pass it on: it would let an agent name any address on the internet and have fal deliver there, which is the opposite of what a pinned host is for. Poll with queue.status and collect with queue.result instead.
• There is no sandbox. fal bills real credit on the first submit. Test with image.generate_fast (FLUX.1 [schnell]) — it is the cheapest and fastest of the pinned pair.
• Concurrency is a queue, not a rejection. A new account runs two requests at once, rising to 40 as you buy credits. Beyond that, submits wait in the queue rather than failing, so a burst shows up as slow rather than broken.
• Generated files are public URLs. Results come back as links on fal's CDN that anyone holding the link can open. Retention is set per request by a header this connector does not forward, so the account default applies; the request payloads behind your dashboard history are kept for 30 days. If an agent's output matters, or if it should not be world-readable, fetch it and store it somewhere you control.
• Cancelling is best effort. A queued request is dropped and never runs; one already on a runner gets a cancellation signal that the model may or may not act on, and fal returns 400 if it had already finished.
• Account billing is out of reach here, by design. fal's usage and billing endpoints live on api.fal.ai, a different host, and the pinned base URL is what stops an agent reaching anywhere but the queue. Check your balance in the fal dashboard instead.