fal.ai API 401 error — how to fix?

fal.ai API 401: the auth scheme must be Key not Bearer. Header: Authorization: Key fal-YOUR_KEY. The key format starts with fal-. Generate at fal.ai/settings/keys. For the JavaScript client: set environment variable FAL_KEY=fal-YOUR_KEY. For Python: FAL_KEY env var or fal.config(credentials='fal-YOUR_KEY').

How do I use fal.ai real-time streaming?

fal.ai Realtime endpoints use WebSocket connections for streaming output (useful for image generation with progressive previews). Use the fal-client library: fal.realtime.connect(MODEL_ID, { onResult: (result) => { ... } }). Realtime is available for Stable Diffusion XL Turbo, FLUX, and other fast models. Not all models support realtime.

fal.ai vs Replicate — which is better?

fal.ai and Replicate are both AI inference platforms. fal.ai specializes in fast GPU inference with WebSocket streaming, lower latency for image generation (FLUX, SDXL), and a cleaner TypeScript/Python client SDK. Replicate has a broader model catalog, Cog for custom model deployment, and better documentation. For speed-critical image generation, fal.ai often has lower latency. For model variety and custom deployments, Replicate is stronger.

Free 5 min read

fal.ai Not Working?

fal.ai API returning 401 (wrong auth scheme), queue timeout, model validation error, billing 402, or real-time WebSocket streaming failing? Check live status and fix it fast.

fal.ai — live status

Updated every 5 minutes. Full history at prismix.dev/service/fal.

Full status →

What's wrong? Diagnose fast

🔑

API 401 — wrong auth scheme

Header must be Authorization: Key fal-YOUR_KEY (not Bearer). API keys start with fal-. Generate at fal.ai/settings/keys. JS: FAL_KEY env var. Python: FAL_KEY or fal.config(credentials=...).

⏳

Queue timeout / slow

Free tier has lower priority. Set 120s+ timeout for heavy models. For production: use fal.queue.submit + poll, or webhooks. Realtime endpoints use WebSockets for streaming output.

❌

Model 422 validation error

Input schema mismatch. Check model page at fal.ai/models/MODEL_ID for exact schema. Common: width/height must be integers not strings. Use the Playground on model page to test inputs first.

💸

Billing 402 error

Credits exhausted or payment failed. Check fal.ai/settings/billing. Add payment method. Free tier has limited monthly credits. Set a spending limit to avoid surprises.

📡

Realtime streaming fails

WebSocket streaming (fal.realtime) requires fal-client library. Not all models support realtime. Check if the model page shows "Realtime" badge. Use fal.queue for non-realtime models.

📦

Model output format unexpected

Different models return output in different shapes. Check model page → Schema tab for the exact output format. Image models return { images: [{ url, width, height }] }. Check URL for expiry — fal CDN URLs expire after a few hours.

fal.ai API quick reference

REST API (curl)

# Submit to queue
curl -X POST "https://queue.fal.run/fal-ai/flux/dev" \
  -H "Authorization: Key fal-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a cat on a mountain"}'
# Returns: { "request_id": "abc123", "status": "IN_QUEUE", ... }

# Poll status
curl "https://queue.fal.run/fal-ai/flux/dev/requests/abc123/status" \
  -H "Authorization: Key fal-YOUR_KEY"
# Get result when COMPLETED
curl "https://queue.fal.run/fal-ai/flux/dev/requests/abc123" \
  -H "Authorization: Key fal-YOUR_KEY"

JavaScript / TypeScript client

import * as fal from "@fal-ai/serverless-client";
// FAL_KEY env var must be set: fal-YOUR_KEY

const result = await fal.subscribe("fal-ai/flux/dev", {
  input: { prompt: "a cat on a mountain", image_size: "landscape_4_3" },
  pollInterval: 3000,
  onQueueUpdate: (update) => console.log("Status:", update.status),
});
console.log(result.images[0].url);

Common auth mistake

Use Authorization: Key fal-YOUR_KEY — NOT Authorization: Bearer fal-YOUR_KEY. The scheme is Key, not Bearer.

Step-by-step fix

1

Check live fal.ai status

Visit prismix.dev/service/fal. If fal.ai is operational, most issues are auth configuration or queue delays during peak demand.
2

Fix API 401 authentication

The most common fal.ai mistake: using Authorization: Bearer instead of Authorization: Key. Your API key starts with fal-. Generate a new key at fal.ai/settings/keys. For JavaScript: set FAL_KEY=fal-YOUR_KEY as an env variable (fal-client reads it automatically).
3

Fix queue timeout / slow responses

Use fal.queue.submit for async processing instead of synchronous calls that timeout. Set a 120-second minimum timeout for large models. For production latency requirements: use Realtime endpoints (WebSocket streaming) for supported models, or upgrade from free tier for higher queue priority.
4

Fix model 422 validation errors

Go to the model page at fal.ai → click the model → Schema tab. Verify all required fields are present. Common fixes: (1) width and height must be integers, not strings; (2) image_size must be one of the enum values shown (e.g. "landscape_4_3" not "4:3"); (3) check optional vs required fields. Use the Playground to confirm inputs work before adding to code.
5

Fix billing issues

Check fal.ai/settings/billing for remaining credits and payment status. fal.ai is pay-as-you-go: each inference costs based on GPU-seconds. Free tier includes limited monthly credits. If 402: add a payment method. Set a spending limit under Billing to cap monthly costs.

🔔

Get alerted when fal.ai goes down

Star fal.ai on Prismix and get emailed the moment status changes. Free, no credit card.