Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/phpaisdk/fal/llms.txt

Use this file to discover all available pages before exploring further.

Configuration for aisdk/fal is handled entirely through FalOptions, a read-only value object that holds every runtime setting for the provider. You never construct FalOptions directly — it is built for you either automatically from environment variables when you call Fal::default() or Fal::model(), or explicitly by passing an associative array to Fal::create(array $config). Both paths call FalOptions::fromArray() internally, so the resolution rules are identical regardless of which approach you choose.

​
Two ways to configure

Environment variables are the simplest approach and the recommended default for production deployments. Set FAL_API_KEY (and optionally FAL_BASE_URL) in your environment and call Fal::default() with no arguments — the provider resolves all settings automatically. Programmatic configuration via Fal::create() is useful when you need multiple provider instances, want to supply a key fetched from a secrets manager at runtime, or need to override poll timeouts for specific workloads. Every key accepted by the array maps one-to-one to a FalOptions constructor parameter.

​
Environment variables

VariablePurpose
FAL_API_KEYPrimary API key. Checked first.
FAL_KEYFallback key name (matches upstream @ai-sdk/fal naming). Used when FAL_API_KEY is absent.
FAL_BASE_URLOverride the default base URL. Optional.

​
Configuration keys

KeyTypeDefaultDescription
apiKeystring—The fal.ai API key. Required if neither env var is set.
baseUrlstringhttps://fal.runBase URL for all non-video requests. Trailing slashes stripped automatically.
headersarray<string, string>[]Additional HTTP headers merged into every request alongside Authorization.
transcriptionPollTimeoutMsint60000Maximum milliseconds to wait for a transcription job.
videoPollIntervalMsint2000Milliseconds between poll requests to queue.fal.run for video jobs.
videoPollTimeoutMsint300000Maximum milliseconds to wait for a video job (5 minutes).
Note: Video generation always submits to and polls queue.fal.run, regardless of what baseUrl is set to. The baseUrl option applies to image, speech, and transcription requests only.

​
Quick-start examples

# Minimum required — everything else uses defaults
export FAL_API_KEY=fal-...

# Optional: override the base URL
export FAL_BASE_URL=https://fal.run

​
Next steps

Authentication

Learn how API keys are resolved, what the Authorization header looks like, and how to supply extra headers.

Options reference

Full reference for every FalOptions parameter with types, defaults, and examples.

Build docs developers (and LLMs) love

Get started for freeTalk to us