FalEx (fal_ex v0.1.0)

View Source

An Elixir client for fal.ai.

FalEx provides a simple interface to run AI models on fal.ai's serverless platform. It supports synchronous execution, queued jobs, streaming responses, and real-time communication.

Installation

Add fal_ex to your list of dependencies in mix.exs:

def deps do
  [
    {:fal_ex, "~> 0.1.0"}
  ]
end

Configuration

The recommended way to configure FalEx is through your application configuration:

# config/config.exs
config :fal_ex,
  api_key: "your-api-key"

# config/runtime.exs (for runtime configuration)
import Config

if config_env() == :prod do
  config :fal_ex,
    api_key: System.fetch_env!("FAL_KEY")
end

You can also use environment variables (these override application config):

export FAL_KEY="your-api-key"

Or configure programmatically at runtime:

FalEx.config(credentials: "your-api-key")

Basic Usage

# Simple synchronous execution
{:ok, result} = FalEx.run("fal-ai/fast-sdxl",
  input: %{
    prompt: "A cute cat wearing a hat"
  }
)

# Queue-based execution with status updates
{:ok, result} = FalEx.subscribe("fal-ai/fast-sdxl",
  input: %{prompt: "A mountain landscape"},
  on_queue_update: fn status -> IO.inspect(status) end
)

# Streaming responses
{:ok, stream} = FalEx.stream("fal-ai/flux/dev",
  input: %{prompt: "A cute robot", image_size: "square"}
)

stream
|> Stream.each(fn chunk -> IO.inspect(chunk) end)
|> Stream.run()

Summary

Functions

Returns a specification to start this module under a supervisor.

Configures the global FalEx client at runtime.

Access the queue client for advanced queue operations.

Access the realtime client for WebSocket connections.

Runs a fal endpoint synchronously.

Starts the FalEx client process.

Access the storage client for file operations.

Streams partial results from a streaming-capable endpoint.

Access the streaming client for advanced streaming operations.

Submits a request to the queue and subscribes to status updates.

Types

run_result()

@type run_result() :: {:ok, FalEx.Types.result()} | {:error, term()}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

config(opts \\ [])

Configures the global FalEx client at runtime.

Note: The recommended way to configure FalEx is through application configuration. Use this function only when you need to override configuration at runtime.

Options

See FalEx.Config.new/1 for available options.

Examples

# Override configuration at runtime
FalEx.config(credentials: System.get_env("FAL_KEY"))

# Configure with multiple options
FalEx.config(
  credentials: {"key_id", "key_secret"},
  proxy_url: "/api/fal/proxy"
)
# In config/config.exs or config/runtime.exs
config :fal_ex,
  api_key: System.get_env("FAL_KEY"),
  base_url: "https://fal.run"

queue()

Access the queue client for advanced queue operations.

realtime()

Access the realtime client for WebSocket connections.

run(endpoint_id, opts \\ [])

@spec run(
  FalEx.Types.endpoint_id(),
  keyword()
) :: run_result()

Runs a fal endpoint synchronously.

Parameters

  • endpoint_id - The endpoint identifier (e.g., "fal-ai/fast-sdxl")
  • opts - Run options including :input

Options

  • :input - The input payload for the model
  • :path - Optional path to append to the endpoint
  • :method - HTTP method (default: :post)
  • :abort_signal - Reference to abort the request

Examples

{:ok, result} = FalEx.run("fal-ai/fast-sdxl",
  input: %{
    prompt: "A beautiful sunset",
    image_size: "square"
  }
)

Notes

This function blocks until the model execution completes. For long-running models, consider using subscribe/2 instead.

start_link(opts \\ [])

Starts the FalEx client process.

This is typically called automatically by the application supervisor.

storage()

Access the storage client for file operations.

stream(endpoint_id, opts \\ [])

@spec stream(
  FalEx.Types.endpoint_id(),
  keyword()
) :: {:ok, Enumerable.t()} | {:error, term()}

Streams partial results from a streaming-capable endpoint.

Returns {:ok, stream} where stream is an Elixir Stream that yields data chunks as they arrive.

Parameters

  • endpoint_id - The endpoint identifier
  • opts - Stream options including :input

Examples

# Stream image generation with progress updates
{:ok, stream} = FalEx.stream("fal-ai/flux/dev",
  input: %{
    prompt: "a cat",
    seed: 6252023,
    image_size: "landscape_4_3",
    num_images: 4
  }
)

# Process each event as it arrives
stream
|> Stream.each(fn event ->
  IO.inspect(event, label: "Stream event")
end)
|> Stream.run()

# Or collect all events and get the final result
case FalEx.stream("fal-ai/flux/dev", input: %{prompt: "a cute robot"}) do
  {:ok, stream} ->
    events = Enum.to_list(stream)
    IO.puts("Received #{length(events)} events")
    # The last event typically contains the final result

  {:error, reason} ->
    IO.puts("Error: #{inspect(reason)}")
end

streaming()

Access the streaming client for advanced streaming operations.

subscribe(endpoint_id, opts \\ [])

@spec subscribe(
  FalEx.Types.endpoint_id(),
  keyword()
) :: run_result()

Submits a request to the queue and subscribes to status updates.

Parameters

  • endpoint_id - The endpoint identifier
  • opts - Run options plus queue-specific options

Options

All options from run/2 plus:

  • :on_queue_update - Callback for status updates
  • :logs - Include logs in status updates (default: false)
  • :webhook_url - URL for webhook notifications
  • :poll_interval - Status poll interval in ms (default: 500)

Examples

{:ok, result} = FalEx.subscribe("fal-ai/fast-sdxl",
  input: %{prompt: "A cute dog"},
  logs: true,
  on_queue_update: fn status ->
    IO.puts("Status: " <> inspect(status.status))
  end
)