fal Serverless Python Runtime

If you want to use this client in another project without publishing it to a registry:

If the target project uses Poetry: Run poetry add <path-to-this-client> from the target project directory.

If the target project does NOT use Poetry:

1. Build a wheel: poetry build -f wheel
2. Install the wheel: pip install <path-to-wheel>

# Build the wheel
poetry build -f wheel

# Install via pip
pip install path/to/dist/openapi_fal_rest-0.1.0-py3-none-any.whl

To regenerate the gRPC definitions in the isolate_proto project, you must install the package in editable mode with development dependencies and run the regeneration tool with a specific isolate version. The <isolate version> argument must be a tag from the isolate GitHub project with the leading v removed.

$ cd projects/isolate_proto
$ pip install -e '.[dev]'
$ python ../../tools/regen_grpc.py --isolate-version <isolate version>
$ pre-commit run --all-files

To use the library, you must first instantiate a client. Use Client for standard requests or AuthenticatedClient if the API requires a token. You can specify a base_url and, for authenticated requests, a token. For internal servers, you can provide a path to a custom certificate bundle via verify_ssl or disable verification by setting it to False (not recommended for production).

from openapi_fal_rest import Client

# Standard client
client = Client(base_url="https://api.example.com")

# Authenticated client
from openapi_fal_rest import AuthenticatedClient
client = AuthenticatedClient(base_url="https://api.example.com", token="SuperSecretToken")

# Authenticated client with custom SSL verification
client = AuthenticatedClient(
    base_url="https://internal_api.example.com", 
    token="SuperSecretToken",
    verify_ssl="/path/to/certificate_bundle.pem",
)

Once you have defined your fal.App class, use the following CLI commands to execute or deploy it:

• Test locally: Use fal run <file_path>::<ClassName> to run the app for testing.
• Deploy to production: Use fal deploy <file_path>::<ClassName> to deploy the app to a persistent endpoint on the fal platform.

# Run for testing
fal run hello_world.py::MyApp

# Deploy to a persistent endpoint
fal deploy hello_world.py::MyApp

Install the fal package via pip to access the Python SDK and the CLI for building and deploying serverless apps.

pip install fal
fal auth login

If you are developing on the repository, you can install the package in editable mode from the repository root using the [dev] extra:

pip install -e 'projects/fal[dev]'

To use the fal serverless Python runtime, install the fal package via pip and authenticate using the CLI.

pip install fal
fal auth login

Install the client and set your authentication key via environment variables.

pip install fal-client
export FAL_KEY="your-api-key"

A fal application is defined by subclassing fal.App and using the @fal.endpoint decorator to define routes. You can test your application locally using the fal run command, which follows the pattern filename.py::ClassName.

import fal


class MyApp(fal.App):
    @fal.endpoint("/")
    def run(self) -> dict:
        return {"message": "Hello, World!"}

The fal-client package is the simplest way to invoke model APIs (like Flux) or your own deployed fal apps from a Python environment.

To use fal-client:

1. Install: pip install fal-client.
2. Configure: Set the FAL_KEY environment variable with your API key.
3. Invoke: Use fal_client.subscribe(model_or_endpoint_id, arguments={...}) to call the service. This works for both hosted model IDs (e.g., fal-ai/flux/schnell) and your own deployed endpoint IDs.

import fal_client

result = fal_client.subscribe(
    "fal-ai/flux/schnell",
    arguments={
        "prompt": "a futuristic cityscape at sunset",
        "image_size": "landscape_16_9",
    },
)

print(result["images"][0]["url"])

The fal package is the SDK and CLI used to define, test, and deploy serverless applications to the fal platform. You use it to build pipelines and serve ML models that scale automatically and scale down to zero when not in use.

To use fal:

1. Install: Use pip install fal.
2. Authenticate: Run fal auth login.
3. Define an App: Inherit from fal.App and use the @fal.endpoint(path) decorator to define endpoints.
4. Test: Run your app on fal using a temporary URL with fal run <file_path>::<ClassName>.
5. Deploy: Deploy to a persistent production endpoint using fal deploy <file_path>::<ClassName>.

import fal

class MyApp(fal.App):
    @fal.endpoint("/")
    def run(self) -> dict:
        return {"message": "Hello, World!"}

If you are developing on the repository itself, you can install the packages in editable mode from the root directory.

pip install -e 'projects/fal[dev]'
pip install -e 'projects/fal_client[dev]'
pip install -e 'projects/isolate_proto[dev]'