fal.ai Python client

This is a Python client library for interacting with ML models deployed on fal.ai.

Getting started

To install the client, run:

pip install fal-client

To use the client, you need to have an API key. You can get one by signing up at fal.ai. Once you have it, set it as an environment variable:

export FAL_KEY=your-api-key

Now you can use the client to interact with your models. Here's an example of how to use it:

import fal_client

response = fal_client.run("fal-ai/fast-sdxl", arguments={"prompt": "a cute cat, realistic, orange"})
print(response["images"][0]["url"])

Asynchronous requests

The client also supports asynchronous requests out of the box. Here's an example:

import asyncio
import fal_client

async def main():
    response = await fal_client.run_async("fal-ai/fast-sdxl", arguments={"prompt": "a cute cat, realistic, orange"})
    print(response["images"][0]["url"])


asyncio.run(main())

Uploading files

If the model requires files as input, you can upload them directly to fal's CDN and pass the URLs to the client. Here's an example:

import fal_client

audio_url = fal_client.upload_file("path/to/audio.wav")
response = fal_client.run("fal-ai/whisper", arguments={"audio_url": audio_url})
print(response["text"])

Encoding files as in-memory data URLs

If you don't want to upload your file to our CDN service (for latency reasons, for example), you can encode it as a data URL and pass it directly to the client. Here's an example:

import fal_client

audio_data_url = fal_client.encode_file("path/to/audio.wav")
response = fal_client.run("fal-ai/whisper", arguments={"audio_url": audio_data_url})
print(response["text"])

Queuing requests

When you want to send a request and keep receiving updates on its status, you can use the submit method. Here's an example:

import asyncio
import fal_client

async def main():
    response = await fal_client.submit_async("fal-ai/fast-sdxl", arguments={"prompt": "a cute cat, realistic, orange"})

    logs_index = 0
    async for event in response.iter_events(with_logs=True):
        if isinstance(event, fal_client.Queued):
            print("Queued. Position:", event.position)
        elif isinstance(event, (fal_client.InProgress, fal_client.Completed)):
            new_logs = event.logs[logs_index:]
            for log in new_logs:
                print(log["message"])
            logs_index = len(event.logs)

    result = await response.get()
    print(result["images"][0]["url"])


asyncio.run(main())

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

fal_client-1.0.1.tar.gz (43.3 kB view details)

Uploaded Aug 19, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

fal_client-1.0.1-py3-none-any.whl (26.9 kB view details)

Uploaded Aug 19, 2026 Python 3

File details

Details for the file fal_client-1.0.1.tar.gz.

File metadata

Download URL: fal_client-1.0.1.tar.gz
Upload date: Aug 19, 2026
Size: 43.3 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for fal_client-1.0.1.tar.gz
Algorithm	Hash digest
SHA256	`46d1cee3426d0a2ad34f32b7dbfbdff83487c3dcf8aeae1aac2ffd5815e2055c`
MD5	`0f76ffade7bdf2831cdde8d94c704bd3`
BLAKE2b-256	`fd625b4c56b998b99b6fadb40f17fea7ba5aff83b5a047dee550d1980d1df968`

See more details on using hashes here.

Provenance

The following attestation bundles were made for fal_client-1.0.1.tar.gz:

Publisher: release.yaml on fal-ai/fal

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: fal_client-1.0.1.tar.gz
- Subject digest: 46d1cee3426d0a2ad34f32b7dbfbdff83487c3dcf8aeae1aac2ffd5815e2055c
- Sigstore transparency entry: 2518769064
- Sigstore integration time: Aug 19, 2026
Source repository:
- Permalink: fal-ai/fal@c0f4efd31b1356fd3b8aa829d25cc08e9e191ccb
- Branch / Tag: refs/tags/fal_client_v1.0.1
- Owner: https://github.com/fal-ai
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yaml@c0f4efd31b1356fd3b8aa829d25cc08e9e191ccb
- Trigger Event: release