Webhooks
For long-running requests, such as training jobs, you can use webhooks to receive the result asynchronously. You can specify the webhook URL when submitting a request.
The client for Python provides a seamless interface to interact with fal.
First, add the client as a dependency in your project:
pip install fal-client
Endpoints requests are managed by a queue system. This allows fal to provide a reliable and scalable service.
The resulting handler
provides a way to wait for the result to be fully ready.
import fal_client
handler = fal_client.submit(
"fal-ai/flux/dev",
arguments={
"prompt": "a cat",
"seed": 6252023,
"image_size": "landscape_4_3",
"num_images": 4
},
)
result = handler.get()
print(result)
You can manage the queue using the following methods:
Submit a request to the queue using the queue.submit
method.
import fal_client
handler = fal_client.submit(
"fal-ai/flux/dev",
arguments={
"prompt": "a cat",
"seed": 6252023,
"image_size": "landscape_4_3",
"num_images": 4
},
)
request_id = handler.request_id
This is useful when you want to submit a request to the queue and retrieve the result later. You can save the request_id
and use it to retrieve the result later.
For long-running requests, such as training jobs, you can use webhooks to receive the result asynchronously. You can specify the webhook URL when submitting a request.
Retrieve the status of a specific request in the queue:
status = handler.status(with_logs=True)
Get the result of a specific request from the queue:
result = handler.get()
Some endpoints require files as input. However, since the endpoints run asynchronously, processed by the queue, you will need to provide URLs to the files instead of the actual file content.
Luckily, the client library provides a way to upload files to the server and get a URL to use in the request.
url = fal_client.upload_file("path/to/file")
Some endpoints support streaming:
import fal_client
def stream():
stream = fal_client.stream(
"fal-ai/flux/dev",
arguments={
"prompt": "a cat",
"seed": 6252023,
"image_size": "landscape_4_3",
"num_images": 4
},
)
for event in stream:
print(event)
if __name__ == "__main__":
stream()
For the endpoints that support real-time inference via WebSockets, you can use the realtime client that abstracts the WebSocket connection, re-connection, serialization, and provides a simple interface to interact with the endpoint:
This functionality is not available on this client yet.
The endpoints can also be called directly instead of using the queue system.
We do not recommend this use most use cases as it will block the client until the response is received. Moreover, if the connection is closed before the response is received, the request will be lost.
import fal_client
result = fal_client.run(
"fal-ai/flux/dev",
arguments={
"prompt": "a cat",
"seed": 6252023,
"image_size": "landscape_4_3",
"num_images": 4
},
)
print(result)
If you encounter any issues or have questions, please visit the GitHub repository (opens in a new tab) or join our Discord Community (opens in a new tab).