Fal

fal

The wire to fal.ai's fast, pre-warmed media endpoints: call a model by id, control the queue, get the file back. fal is the fast-media path — latency-optimized image (FLUX, Seedream, SD), audio (TTS, music), and video (Veo, Wan, Kling, Hailuo) endpoints you invoke by id with FAL_KEY.

You own the mechanics: auth, call mode, queue states, webhook signatures, file I/O, per-call cost.

When NOT to use

Rule: if you are not invoking a fal endpoint id with FAL_KEY, you are in the wrong skill.

Setup & auth

# JS — current client. NOT @fal-ai/serverless-client (deprecated, migrate).
npm i @fal-ai/client          # latest 1.10.1

# Python
pip install fal-client

export FAL_KEY="key_id:key_secret"

import { fal } from "@fal-ai/client";
// Reads FAL_KEY from env automatically; or set it explicitly:
fal.config({ credentials: process.env.FAL_KEY });

Rule: never ship FAL_KEY to a browser bundle. Proxy every call through your own server. Why: a key in client-side JS lets anyone drain your account — fal endpoints bill per call with no per-request cap.

Pick a call mode

All three modes hit the same queue. Choose by how long the job runs and where you call it from.

// Bad: run() on a 60s video — connection can drop, no retry, no progress.
const res = await fal.run("fal-ai/veo3", { input });

// Good: submit + webhook for anything that takes more than a few seconds.
const { request_id } = await fal.queue.submit("fal-ai/veo3", {
  input,
  webhookUrl: "https://api.example.com/fal/webhook",
});

subscribe — block and stream progress

const result = await fal.subscribe("fal-ai/flux/dev", {
  input: { prompt: "a red bicycle on a wet street, cinematic" },
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS") {
      update.logs?.forEach((l) => console.log(l.message)); // stream to user
    }
  },
});
console.log(result.data.images[0].url); // hosted output URL

import fal_client

def on_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
            print(log["message"])

result = fal_client.subscribe(
    "fal-ai/flux/dev",
    arguments={"prompt": "a red bicycle on a wet street, cinematic"},
    with_logs=True,
   
)
print(result["images"][0]["url"])

Python has an async twin for every method — subscribe_async, submit_async, run_async. Use them inside an event loop.

submit + queue polling

When you cannot or will not block, submit and poll the queue yourself.

const { request_id } = await fal.queue.submit("fal-ai/flux/dev", { input });

// Poll. Status moves IN_QUEUE -> IN_PROGRESS -> COMPLETED.
const status = await fal.queue.status("fal-ai/flux/dev", {
  requestId: request_id,
  logs: true,
});

// Once COMPLETED, fetch the result.
const result = await fal.queue.result("fal-ai/flux/dev", { requestId: request_id });
console.log(result.data.images[0].url);

Rule: back off between polls — start at ~1s, grow to a few seconds. Why: a tight while loop polling queue.status hammers the API and gains nothing; the job finishes when it finishes. For anything long-running, prefer a webhook over any polling at all.

Webhooks

Pass webhook_url (camelCase webhookUrl in the JS client) on submit; fal POSTs the result when the job finishes.

// Success
{ "request_id": "...", "gateway_request_id": "...", "status": "OK", "payload": { /* result */ } }
// Failure
{ "request_id": "...", "status": "ERROR", "error": "..." }
// Result couldn't be serialized
{ "request_id": "...", "status": "OK", "payload": null, "payload_error": "..." }

Delivery facts you must design for:

• The initial POST has a 15-second timeout. On timeout or non-2xx, fal retries up to 10 times over ~2 hours.
• Therefore your handler must be idempotent — the same request_id can arrive more than once. Dedupe on request_id (e.g. an upsert keyed on it) before acting.
• Verify the ED25519 signature before trusting the body — four X-Fal-Webhook-* headers + a JWKS fetched from https://rest.fal.ai/.well-known/jwks.json. Why: an unverified webhook endpoint is a public write to your DB / spend trigger.

The full verification (header parsing, JWKS caching, ±5-minute timestamp check, message construction, per-key verify) and a complete idempotent handler in Node and Python live in references/queue-and-webhooks.md.

File inputs and outputs

Upload a local file to get a URL, then pass that URL into input for image-to-X jobs. Outputs always come back as hosted URLs.

const url = await fal.storage.upload(file); // File/Blob -> hosted URL
const out = await fal.subscribe("fal-ai/flux/dev/image-to-image", {
  input: { image_url: url, prompt: "make it snow" },
});

url = fal_client.upload_file("input.png")
out = fal_client.subscribe(
    "fal-ai/flux/dev/image-to-image",
    arguments={"image_url": url, "prompt": "make it snow"},
)

Cost control

Pricing is pay-per-use, per-model unit — never flat. The unit differs by model, so always read the model's pricing tab before you ship a loop.

Spend knobs, by modality:

• Image: lower num_inference_steps, drop resolution / megapixels, cut num_images.
• Video: shorten duration, lower fps/resolution — per-second pricing scales linearly.
• Batch: fal batch inference is 50% of serverless price — use it for offline bulk jobs where latency does not matter.

Worked estimate: 500 Seedream V4 images at ~$0.03 ≈ $15 serverless, ≈ $7.50 on the batch path.

The full model-family map and per-modality knob list live in references/models-and-cost.md.

Anti-patterns