fal-rs

A Rust client for the fal.ai API, providing easy access to state-of-the-art AI models for image generation, audio processing, and more.

Features

• Type-safe API: Strongly typed interfaces for all fal.ai endpoints, generated and kept up-to-date straight from the API itself
• Async/Await Support: Built on top of reqwest for efficient async operations
• Queue System: Built-in support for fal.ai's queue system for long-running operations
• Image Processing: Optional image processing capabilities with the image feature

Installation

Add this to your Cargo.toml:

[dependencies]
fal = "0.1"

Usage

Using public model endpoints

By default, the endpoints feature is enabled, and you can use pre-built, fully-typed endpoint functions to call the API:

use fal::prelude::*;

#[tokio::main]
async fn main() {
    // Use the Flux Pro endpoint to generate an image
    let response = fal::endpoints::fal_ai::flux_pro::flux_pro(FluxProTextToImageInput {
        prompt: "a majestic horse in a field".to_string(),
        ..Default::default()
    })
    .with_api_key("fal_api_key_here") // If not provided, the FAL_API_KEY environment variable is used
    .send()
    .await
    .unwrap();

    println!("Generated image URL: {}", response.images[0].url);
}

Using the Queue System

For long-running operations, you can use the FAL Queue API:

use fal::prelude::*;
use futures::StreamExt;

#[tokio::main]
async fn main() {
    let queue = fal::endpoints::fal_ai::flux_pro::flux_pro(FluxProTextToImageInput {
        prompt: "a majestic horse in a field".to_string(),
        ..Default::default()
    })
    .queue()
    .await
    .unwrap();

    // Stream status updates
    while let Some(status) = queue.stream(true).await.unwrap().next().await {
        let status = status.unwrap();
        println!("Status: {:?}", status.status);
        
        if status.status == Status::Completed {
            break;
        }
    }

    let response = queue.response().await.unwrap();
    println!("Generated image URL: {}", response.images[0].url);
}

The #[endpoint] macro

You can easily create a custom endpoint function using the provided endpoint proc macro. This should only be necessary if you disable the endpoints feature, or you are using a private model endpoint.

use fal::prelude::*;
use serde::Deserialize;

#[derive(Deserialize)]
pub struct FalResponse {
  pub images: Vec<File>,
}

#[endpoint(endpoint="fal-ai/flux/dev")]
pub fn flux_dev(prompt: String) -> FalResponse {}

// This endpoint function can now be used to call the fal endpoint:
#[tokio::main]
async fn main() {
    let response = flux_dev("an horse riding an astronaut".to_owned())
    .send()
    .await
    .unwrap();

    println!("Generated image URL: {}", response.images[0].url);
}

Features

The crate comes with several optional features:

• image (enabled by default): Provides image processing capabilities using the image crate
• endpoints (enabled by default): Includes pre-generated endpoint modules for fal.ai services

Generating Endpoint Modules

The generate package in this repository is used to automatically generate endpoint modules based on the fal.ai API specification. This ensures that the client always has up-to-date type definitions and endpoint implementations.

To generate endpoint modules:

1. Clone the repository
2. Run the generate package:

cargo run -p generate-endpoints

This will update the endpoint modules in the fal/src/endpoints directory with the latest API definitions, using the model registry from the FAL API.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

We welcome contributions! Please feel free to submit a Pull Request.