0
# fal-client
1

2
A comprehensive Python client library for interacting with machine learning models deployed on the fal.ai platform. It offers both synchronous and asynchronous API interfaces for executing ML models, supporting various input formats including direct file uploads to fal.media CDN and in-memory data URL encoding for latency-sensitive applications.
3

4
## Package Information
5

6
- **Package Name**: fal-client
7
- **Language**: Python
8
- **Installation**: `pip install fal-client`
9
- **Minimum Python Version**: 3.8+
10

11
## Core Imports
12

13
```python
14
import fal_client
15
```
16

17
For direct access to client classes:
18

19
```python
20
from fal_client import SyncClient, AsyncClient
21
```
22

23
For status and handle classes:
24

25
```python
26
from fal_client import Queued, InProgress, Completed, SyncRequestHandle, AsyncRequestHandle
27
```
28

29
For encoding utilities:
30

31
```python
32
from fal_client import encode, encode_file, encode_image
33
```
34

35
## Basic Usage
36

37
```python
38
import fal_client
39

40
# Set your API key as an environment variable
41
# export FAL_KEY=your-api-key
42

43
# Simple synchronous inference
44
response = fal_client.run("fal-ai/fast-sdxl", arguments={"prompt": "a cute cat, realistic, orange"})
45
print(response["images"][0]["url"])
46

47
# File upload and processing
48
audio_url = fal_client.upload_file("path/to/audio.wav")
49
response = fal_client.run("fal-ai/whisper", arguments={"audio_url": audio_url})
50
print(response["text"])
51

52
# Asynchronous execution with queue tracking
53
import asyncio
54

55
async def main():
56
    handle = await fal_client.submit_async("fal-ai/fast-sdxl", arguments={"prompt": "a cute cat"})
57
    
58
    # Monitor progress
59
    async for event in handle.iter_events(with_logs=True):
60
        if isinstance(event, fal_client.Queued):
61
            print(f"Queued. Position: {event.position}")
62
        elif isinstance(event, fal_client.InProgress):
63
            print("Processing...")
64
        elif isinstance(event, fal_client.Completed):
65
            break
66
    
67
    result = await handle.get()
68
    print(result["images"][0]["url"])
69

70
asyncio.run(main())
71
```
72

73
## Architecture
74

75
The fal-client library follows a dual-interface architecture:
76

77
- **Global Functions**: Direct access to fal.ai services through module-level functions (`fal_client.run()`, `fal_client.submit()`, etc.)
78
- **Client Classes**: Explicit client instances (`SyncClient`, `AsyncClient`) for advanced configuration and lifecycle management
79
- **Request Handles**: Objects that manage the lifecycle of long-running requests with status monitoring and cancellation capabilities
80
- **Status System**: Type-safe status indicators (`Queued`, `InProgress`, `Completed`) for tracking request progress
81
- **File Management**: Integrated CDN upload capabilities and in-memory encoding for various input formats
82

83
This design provides both simple function-based usage for quick tasks and sophisticated request management for complex workflows.
84

85
## Capabilities
86

87
### Synchronous Operations
88

89
Direct execution and queue-based operations with blocking I/O. Includes immediate inference execution, queue submission with status monitoring, CDN file uploads, and request management operations.
90

91
```python { .api }
92
def run(application: str, arguments: AnyJSON, *, path: str = "", timeout: float | None = None, hint: str | None = None) -> AnyJSON: ...
93
def submit(application: str, arguments: AnyJSON, *, path: str = "", hint: str | None = None, webhook_url: str | None = None, priority: Priority | None = None) -> SyncRequestHandle: ...
94
def subscribe(application: str, arguments: AnyJSON, *, path: str = "", hint: str | None = None, with_logs: bool = False, on_enqueue: callable[[str], None] | None = None, on_queue_update: callable[[Status], None] | None = None, priority: Priority | None = None) -> AnyJSON: ...
95
def stream(application: str, arguments: AnyJSON, *, path: str = "/stream", timeout: float | None = None) -> Iterator[dict[str, Any]]: ...
96
def upload(data: bytes | str, content_type: str, file_name: str | None = None) -> str: ...
97
def upload_file(path: PathLike) -> str: ...
98
def upload_image(image: "Image.Image", format: str = "jpeg") -> str: ...
99
def status(application: str, request_id: str, *, with_logs: bool = False) -> Status: ...
100
def result(application: str, request_id: str) -> AnyJSON: ...
101
def cancel(application: str, request_id: str) -> None: ...
102
```
103

104
[Synchronous Operations](./sync-operations.md)
105

106
### Asynchronous Operations
107

108
Non-blocking async/await operations for concurrent execution. Mirrors synchronous operations but with async coroutines for high-performance applications requiring concurrent model inference and request management.
109

110
```python { .api }
111
async def run_async(application: str, arguments: AnyJSON, *, path: str = "", timeout: float | None = None, hint: str | None = None) -> AnyJSON: ...
112
async def submit_async(application: str, arguments: AnyJSON, *, path: str = "", hint: str | None = None, webhook_url: str | None = None, priority: Priority | None = None) -> AsyncRequestHandle: ...
113
async def subscribe_async(application: str, arguments: AnyJSON, *, path: str = "", hint: str | None = None, with_logs: bool = False, on_enqueue: callable[[str], None] | None = None, on_queue_update: callable[[Status], None] | None = None, priority: Priority | None = None) -> AnyJSON: ...
114
async def stream_async(application: str, arguments: AnyJSON, *, path: str = "/stream", timeout: float | None = None) -> AsyncIterator[dict[str, Any]]: ...
115
async def upload_async(data: bytes | str, content_type: str, file_name: str | None = None) -> str: ...
116
async def upload_file_async(path: PathLike) -> str: ...
117
async def upload_image_async(image: "Image.Image", format: str = "jpeg") -> str: ...
118
async def status_async(application: str, request_id: str, *, with_logs: bool = False) -> Status: ...
119
async def result_async(application: str, request_id: str) -> AnyJSON: ...
120
async def cancel_async(application: str, request_id: str) -> None: ...
121
```
122

123
[Asynchronous Operations](./async-operations.md)
124

125
### Request Management
126

127
Status tracking, cancellation, and result retrieval for long-running inference tasks. Provides handle-based request lifecycle management with real-time status updates and event streaming capabilities.
128

129
```python { .api }
130
class SyncRequestHandle:
131
    request_id: str
132
    def status(self, *, with_logs: bool = False) -> Status: ...
133
    def iter_events(self, *, with_logs: bool = False, interval: float = 0.1) -> Iterator[Status]: ...
134
    def cancel(self) -> None: ...
135
    def get(self) -> AnyJSON: ...
136

137
class AsyncRequestHandle:
138
    request_id: str
139
    async def status(self, *, with_logs: bool = False) -> Status: ...
140
    async def iter_events(self, *, with_logs: bool = False, interval: float = 0.1) -> AsyncIterator[Status]: ...
141
    async def cancel(self) -> None: ...
142
    async def get(self) -> AnyJSON: ...
143
```
144

145
[Request Management](./request-management.md)
146

147
### File Processing
148

149
File upload to fal.media CDN and in-memory data URL encoding. Supports various file formats with automatic MIME type detection and provides both CDN upload for persistent storage and data URL encoding for immediate use.
150

151
```python { .api }
152
def upload_file(path: PathLike) -> str: ...
153
def upload_image(image: "Image.Image", format: str = "jpeg") -> str: ...
154
def encode_file(path: PathLike) -> str: ...
155
def encode_image(image: "Image.Image", format: str = "jpeg") -> str: ...
156
def encode(data: str | bytes, content_type: str) -> str: ...
157
```
158

159
[File Processing](./file-processing.md)
160

161
### Authentication and Configuration
162

163
API key management, Google Colab integration, and client configuration. Handles credential discovery from environment variables, Google Colab userdata, and provides custom client initialization with timeout and authentication settings.
164

165
```python { .api }
166
class SyncClient:
167
    def __init__(self, key: str | None = None, default_timeout: float = 120.0): ...
168

169
class AsyncClient:
170
    def __init__(self, key: str | None = None, default_timeout: float = 120.0): ...
171

172
def fetch_credentials() -> str: ...
173
class MissingCredentialsError(Exception): ...
174
```
175

176
[Authentication and Configuration](./auth-config.md)
177

178
## Types
179

180
```python { .api }
181
from typing import Dict, Any, Literal, Iterator, AsyncIterator
182
from os import PathLike
183

184
# Type aliases
185
AnyJSON = Dict[str, Any]
186
Priority = Literal["normal", "low"]
187

188
class Status: ...
189

190
class Queued(Status):
191
    position: int
192

193
class InProgress(Status):
194
    logs: list[dict[str, Any]] | None
195

196
class Completed(Status):
197
    logs: list[dict[str, Any]] | None
198
    metrics: dict[str, Any]
199

200
class FalClientError(Exception):
201
    """Raised when fal.ai API returns an error response."""
202

203
class MissingCredentialsError(Exception):
204
    """Raised when API credentials cannot be found."""
205
```