fal-client

0.13.2 · active · verified Sat Apr 11

The `fal-client` library is a Python client for fal.ai, providing a streamlined interface to interact with machine learning models deployed on the fal.ai platform. It abstracts away authentication, handles retries, and offers a clean API for various inference methods, including synchronous and asynchronous calls. Currently at version 0.13.2, the library maintains an active development and release cadence.

Warnings

gotcha Authentication requires setting the `FAL_KEY` environment variable for server-side applications. The client automatically picks this up. Without it, API calls will fail.
Fix: Set `export FAL_KEY="YOUR_API_KEY_HERE"` in your shell or programmatically before initializing/using `fal_client`. Obtain your API key from the fal.ai dashboard.
gotcha The `fal-client` provides both synchronous (`fal_client.run`, `fal_client.subscribe`, `fal_client.submit`) and asynchronous (`fal_client.run_async`, `fal_client.subscribe_async`, `fal_client.submit_async`) methods for interacting with models. Ensure you use the correct method matching your application's concurrency model (e.g., `await` for async calls).
Fix: For blocking operations, use `fal_client.run()`. For non-blocking, event-driven applications, use `await fal_client.run_async()` within an `async` function.
gotcha The library is in `0.x.x` versioning, indicating that breaking changes may occur more frequently between minor versions. Always consult the changelog (if available) or official documentation when upgrading.
Fix: Pin your dependency to a specific minor version (e.g., `fal-client==0.13.*`) and review release notes or the fal.ai changelog before upgrading to new minor versions.
gotcha Fal.ai returns structured error responses with `error_type` fields for both model validation failures and infrastructure-level issues (e.g., timeouts, runner failures). Generic error handling might obscure specific root causes.
Fix: Implement specific error handling logic by inspecting the `error_type` field in the response. This allows differentiating between client-side input issues and transient server-side problems that might be retryable.

Install

pip install fal-client Install `fal-client`

Imports

fal_client
```
import fal_client
```

Quickstart

This quickstart demonstrates how to perform a synchronous inference call using the `fal-client`. It requires the `FAL_KEY` environment variable to be set for authentication with fal.ai.

import fal_client
import os

# Ensure FAL_KEY is set in your environment (e.g., export FAL_KEY="YOUR_API_KEY")
# Get your API key from fal.ai
fal_key = os.environ.get('FAL_KEY', '')
if not fal_key:
    print("Warning: FAL_KEY environment variable not set. Please configure your API key for fal.ai.")

# Example of synchronous inference using a public model
try:
    response = fal_client.run(
        "fal-ai/fast-sdxl",
        arguments={
            "prompt": "a cute cat, realistic, orange, 4k"
        }
    )
    if response and "images" in response and response["images"]:
        print(f"Generated image URL: {response['images'][0]['url']}")
    else:
        print("No image URL found in the response.")
except Exception as e:
    print(f"An error occurred during inference: {e}")

view raw JSON →