Install & Compatibility
Where this runs
tested against v1.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.432s · 25.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.7s · import 0.380s · 26MB
24MB installed
● package 24MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
fal_client
✓ import fal_client
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}")
Debug
Known issues
gotchaAuthentication requires setting the `FAL_KEY` environment variable for server-side applications. The client automatically picks this up. Without it, API calls will fail.fixSet `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.
affects: All versions
gotchaThe `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).fixFor blocking operations, use `fal_client.run()`. For non-blocking, event-driven applications, use `await fal_client.run_async()` within an `async` function.
affects: All versions
gotchaThe 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.fixPin 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.
affects: All 0.x.x versions
gotchaFal.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.fixImplement 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.
affects: All versions
Errors
Common errors & fixes
Authorization failed - please check your credentials. Cannot access application
FAL_KEY not set or invalid
fixexport FAL_KEY="your-api-key" — get from fal.ai dashboard
FalServerlessError: [401] Unauthorized
FAL_KEY missing or expired
fixos.environ["FAL_KEY"] = "your-key" or pass key= to FalClient()
ModuleNotFoundError: No module named 'fal_client'
fal-client not installed
fixpip install fal-client
fal_client.submit() returns a request handle, not a result
submit() is async/queued — returns SyncRequestHandle, not the output
fixUse fal_client.run() for direct result, or call handle.get() after submit()
TypeError: object NoneType can't be awaited
Awaiting synchronous method or calling async method outside async context
fixUse fal_client.run() sync or fal_client.run_async() inside async def
{"detail":"Request timed out","error_type":"request_timeout"}
Inference exceeded timeout limit
fixPass client_timeout=300 to fal_client.run() for long-running models
Upgrade
Version history
1.0.1latest on PyPI · released Aug 19, 2026
Audit
Dependencies
httpxrequiredHTTP client for API requests
anyiorequiredAsync I/O support for run_async()