FalEx (fal_ex v0.1.0)
View SourceAn 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
@type run_result() :: {:ok, FalEx.Types.result()} | {:error, term()}
Functions
Returns a specification to start this module under a supervisor.
See Supervisor
.
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"
)
Application Configuration (Recommended)
# In config/config.exs or config/runtime.exs
config :fal_ex,
api_key: System.get_env("FAL_KEY"),
base_url: "https://fal.run"
Access the queue client for advanced queue operations.
Access the realtime client for WebSocket connections.
@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.
Starts the FalEx client process.
This is typically called automatically by the application supervisor.
Access the storage client for file operations.
@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 identifieropts
- 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
Access the streaming client for advanced streaming operations.
@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 identifieropts
- 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
)