fal-api-reference

Complete fal.ai API reference system. PROACTIVELY activate for: (1) @fal-ai/client JavaScript setup, (2) fal_client Python setup, (3) fal.subscribe/run/stream methods, (4) Queue management (submit/status/result), (5) Webhook configuration, (6) File upload to fal.media, (7) REST API endpoints, (8) Real-time WebSocket connections, (9) Error handling patterns. Provides: Client configuration, method signatures, queue workflow, webhook payloads, common parameters. Ensures correct API usage with proper authentication and error handling.

⭐4stars🔀1forks📁View on GitHub🕐Updated Jan 9, 2026

When & Why to Use This Skill

This Claude skill provides a comprehensive reference for the fal.ai API, covering JavaScript and Python SDKs, REST endpoints, and real-time WebSocket connections. It streamlines the integration of generative AI models by offering clear guidance on client setup, queue management, webhook configuration, and file storage, ensuring developers can implement robust and scalable AI workflows with ease.

Use Cases

  • Configuring @fal-ai/client in JavaScript/TypeScript environments with secure credential management and proxy settings.
  • Implementing queue-based execution using fal.subscribe() to handle long-running AI generation tasks with automatic polling and status updates.
  • Integrating real-time interactive features into web applications using WebSocket connections for low-latency AI model feedback.
  • Setting up Python-based AI pipelines using fal-client for synchronous or asynchronous model execution and media file handling.
  • Designing robust error handling and rate-limiting strategies for high-volume AI application deployments using REST endpoints and webhooks.
namefal-api-reference
descriptionComplete fal.ai API reference system. PROACTIVELY activate for: (1) @fal-ai/client JavaScript setup, (2) fal_client Python setup, (3) fal.subscribe/run/stream methods, (4) Queue management (submit/status/result), (5) Webhook configuration, (6) File upload to fal.media, (7) REST API endpoints, (8) Real-time WebSocket connections, (9) Error handling patterns. Provides: Client configuration, method signatures, queue workflow, webhook payloads, common parameters. Ensures correct API usage with proper authentication and error handling.

Quick Reference

Method Use Case Code
fal.subscribe() Queue-based (recommended) await fal.subscribe("model", { input })
fal.run() Fast endpoints (<30s) await fal.run("model", { input })
fal.stream() Progressive output for await (const event of stream) {}
fal.realtime.connect() WebSocket interactive fal.realtime.connect("model", callbacks)
Queue Method Purpose
fal.queue.submit() Submit job, get request_id
fal.queue.status() Check job status
fal.queue.result() Get completed result
fal.queue.cancel() Cancel pending job
Auth Header Format
API Key Authorization Key YOUR_FAL_KEY

When to Use This Skill

Use for API integration fundamentals:

  • Setting up fal.ai client in JavaScript/TypeScript
  • Setting up fal_client in Python
  • Choosing between subscribe, run, and stream methods
  • Implementing webhook callbacks
  • Uploading files to fal.media CDN

Related skills:

  • For model selection: see fal-model-guide
  • For performance optimization: see fal-optimization
  • For custom model deployment: see fal-serverless-guide

fal.ai API Reference

Complete API reference for fal.ai client libraries and REST endpoints.

Client Libraries

JavaScript/TypeScript (@fal-ai/client)

npm install @fal-ai/client

Configuration

import { fal } from "@fal-ai/client";

// Configure credentials (reads FAL_KEY from environment by default)
fal.config({
  credentials: process.env.FAL_KEY,
  // Optional: custom proxy URL for browser apps
  proxyUrl: "https://your-server.com/api/fal-proxy"
});

Core Methods

fal.subscribe(endpoint, options) Queue-based execution with automatic polling. Recommended for most use cases.

const result = await fal.subscribe("fal-ai/flux/dev", {
  input: {
    prompt: "A beautiful landscape"
  },
  logs: true,
  pollInterval: 1000,  // Poll every second (default: 1000)
  onQueueUpdate: (update) => {
    // update.status: "IN_QUEUE" | "IN_PROGRESS" | "COMPLETED"
    if (update.status === "IN_PROGRESS") {
      update.logs?.forEach(log => console.log(log.message));
    }
  }
});

fal.run(endpoint, options) Direct/synchronous execution. Use only for fast endpoints (< 30 seconds).

const result = await fal.run("fal-ai/fast-sdxl", {
  input: { prompt: "A cat" }
});

fal.stream(endpoint, options) Server-sent events for progressive output.

const stream = await fal.stream("fal-ai/flux/dev", {
  input: { prompt: "A landscape" }
});

for await (const event of stream) {
  console.log("Progress:", event);
}

const finalResult = await stream.done();

fal.realtime.connect(endpoint, callbacks) WebSocket connection for real-time interactive applications.

const connection = fal.realtime.connect("fal-ai/lcm-sd15-i2i", {
  connectionKey: "unique-session-id",
  throttleInterval: 128,  // Debounce inputs (ms)
  onResult: (result) => console.log("Generated:", result),
  onError: (error) => console.error("Error:", error),
  onOpen: () => console.log("Connected"),
  onClose: () => console.log("Disconnected")
});

// Send inputs
connection.send({
  prompt: "A cute cat",
  image_url: "https://example.com/base.jpg"
});

// Close when done
connection.close();

Queue Methods

Manual queue management for advanced control.

// Submit to queue
const { request_id } = await fal.queue.submit("fal-ai/flux/dev", {
  input: { prompt: "Test" },
  webhookUrl: "https://your-server.com/webhook"  // Optional
});

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

// Get result (blocks until complete)
const result = await fal.queue.result("fal-ai/flux/dev", {
  requestId: request_id
});

// Cancel request
await fal.queue.cancel("fal-ai/flux/dev", {
  requestId: request_id
});

Storage Methods

Upload files to fal.media CDN.

// Upload File object
const file = new File([blob], "image.png", { type: "image/png" });
const url = await fal.storage.upload(file);

// Upload from URL
const response = await fetch("https://example.com/image.jpg");
const blob = await response.blob();
const url = await fal.storage.upload(new File([blob], "image.jpg"));

Python (fal-client)

pip install fal-client

Synchronous API

import fal_client

# Simple run
result = fal_client.run(
    "fal-ai/flux/dev",
    arguments={
        "prompt": "A beautiful landscape",
        "image_size": "landscape_16_9"
    }
)

# Subscribe with status updates
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": "Test"},
    with_logs=True,
    on_queue_update=on_update
)

# Manual queue management
handler = fal_client.submit(
    "fal-ai/flux/dev",
    arguments={"prompt": "Test"}
)
print(f"Request ID: {handler.request_id}")
status = handler.status()  # Check status
result = handler.get()     # Block until complete

Async API

import asyncio
import fal_client

async def generate():
    # Async run
    result = await fal_client.run_async(
        "fal-ai/flux/dev",
        arguments={"prompt": "Test"}
    )

    # Async subscribe
    result = await fal_client.subscribe_async(
        "fal-ai/flux/dev",
        arguments={"prompt": "Test"},
        with_logs=True
    )

    # Async queue management
    handler = await fal_client.submit_async(
        "fal-ai/flux/dev",
        arguments={"prompt": "Test"}
    )
    status = await handler.status_async()
    result = await handler.get_async()

    return result

result = asyncio.run(generate())

File Upload

# Upload file from path
url = fal_client.upload_file("path/to/image.png")

# Upload bytes
with open("image.png", "rb") as f:
    url = fal_client.upload(f.read(), "image/png")

# Encode as data URL (small files only)
data_url = fal_client.encode_file("small_image.png")

REST API

Base URLs

Purpose URL Pattern
Queue Submit https://queue.fal.run/{model_id}
Queue Status https://queue.fal.run/{model_id}/requests/{request_id}/status
Queue Result https://queue.fal.run/{model_id}/requests/{request_id}
Queue Cancel https://queue.fal.run/{model_id}/requests/{request_id}/cancel
Direct Run https://fal.run/{model_id}
WebSocket wss://fal.run/{model_id}

Authentication

Authorization: Key YOUR_FAL_KEY

Queue Workflow

# 1. Submit to queue
curl -X POST "https://queue.fal.run/fal-ai/flux/dev" \
  -H "Authorization: Key $FAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A beautiful landscape",
    "image_size": "landscape_16_9"
  }'

# Response:
# {
#   "request_id": "abc123-def456",
#   "status": "IN_QUEUE",
#   "queue_position": 0
# }

# 2. Check status
curl "https://queue.fal.run/fal-ai/flux/dev/requests/abc123-def456/status" \
  -H "Authorization: Key $FAL_KEY"

# Response (in progress):
# {
#   "status": "IN_PROGRESS",
#   "logs": [{"message": "Loading model...", "timestamp": "..."}]
# }

# Response (completed):
# {
#   "status": "COMPLETED"
# }

# 3. Get result
curl "https://queue.fal.run/fal-ai/flux/dev/requests/abc123-def456" \
  -H "Authorization: Key $FAL_KEY"

# Response:
# {
#   "images": [{"url": "https://fal.media/...", "width": 1024, "height": 576}],
#   "seed": 12345,
#   "prompt": "A beautiful landscape"
# }

Webhooks

Submit with webhook URL to receive results via POST:

curl -X POST "https://queue.fal.run/fal-ai/flux/dev" \
  -H "Authorization: Key $FAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Test",
    "webhook_url": "https://your-server.com/webhook"
  }'

Webhook payload:

{
  "request_id": "abc123",
  "status": "COMPLETED",
  "payload": {
    "images": [{"url": "https://fal.media/..."}]
  }
}

Direct Execution

For fast endpoints (< 30 seconds):

curl -X POST "https://fal.run/fal-ai/fast-sdxl" \
  -H "Authorization: Key $FAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A cat"}'

Common Model Parameters

FLUX Models

interface FluxInput {
  prompt: string;                    // Required
  image_size?:
    | "square_hd"      // 1024x1024
    | "square"         // 512x512
    | "portrait_4_3"   // 768x1024
    | "portrait_16_9"  // 576x1024
    | "landscape_4_3"  // 1024x768
    | "landscape_16_9" // 1024x576
    | { width: number; height: number };
  num_inference_steps?: number;      // 1-50, default: 28
  guidance_scale?: number;           // 1-20, default: 3.5
  num_images?: number;               // 1-4, default: 1
  seed?: number;                     // For reproducibility
  enable_safety_checker?: boolean;   // Default: true
  output_format?: "jpeg" | "png";    // Default: jpeg
  sync_mode?: boolean;               // Wait for completion
}

interface FluxOutput {
  images: Array<{
    url: string;
    width: number;
    height: number;
    content_type: string;
  }>;
  seed: number;
  prompt: string;
  has_nsfw_concepts?: boolean[];
  timings?: {
    inference: number;
  };
}

Video Models

interface VideoInput {
  prompt: string;
  negative_prompt?: string;
  duration?: number;          // seconds
  aspect_ratio?: "16:9" | "9:16" | "1:1" | "4:3" | "21:9";
  cfg_scale?: number;         // 0.0-1.0
  seed?: number;
  // Model-specific options...
}

interface VideoOutput {
  video: {
    url: string;
    content_type: string;
    file_size?: number;
  };
  audio?: {
    url: string;
  };
  seed: number;
}

Audio Models (Whisper)

interface WhisperInput {
  audio_url: string;
  task?: "transcribe" | "translate";
  language?: string;         // ISO code
  chunk_level?: "segment";
  version?: "3";
}

interface WhisperOutput {
  text: string;
  chunks?: Array<{
    text: string;
    timestamp: [number, number];
  }>;
}

Error Responses

// 400 Bad Request - Validation error
{
  "detail": "Invalid input",
  "errors": [
    {"field": "prompt", "message": "Field is required"}
  ]
}

// 401 Unauthorized
{
  "detail": "Invalid API key"
}

// 429 Too Many Requests
{
  "detail": "Rate limit exceeded",
  "retry_after": 60
}

// 500 Internal Server Error
{
  "detail": "Internal server error",
  "request_id": "abc123"
}

Rate Limits

  • Rate limits vary by subscription tier
  • Implement exponential backoff for 429 responses
  • Use webhooks for high-volume applications
  • Contact fal.ai for enterprise rate limits

SDK Versions

Library Latest Version Install
@fal-ai/client 0.15+ npm install @fal-ai/client
fal-client (Python) 0.4+ pip install fal-client
fal (Serverless) 0.13+ pip install fal

Always check https://docs.fal.ai for the latest API documentation and updates.