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.

FalOptions is the immutable value object that holds all runtime configuration for the aisdk/fal provider. It is created via the static factory FalOptions::fromArray(), which is called internally whenever you call Fal::create(array $config) or let the provider initialise itself from environment variables via Fal::default(). You never need to instantiate FalOptions yourself — the array-based API is the intended surface.

​
Parameters

​
apiKey
string
required
The fal.ai API key used to authenticate every request. If not supplied in the config array, the provider reads FAL_API_KEY from the environment, falling back to FAL_KEY if the primary variable is absent. A missing key with no env var fallback will throw at construction time.
​
baseUrl
string
default:"https://fal.run"
The base URL prepended to all image, speech, and transcription request paths. Can be overridden via the FAL_BASE_URL environment variable or the baseUrl config key. Trailing slashes are stripped automatically by Url::withoutTrailingSlash() so paths are always joined cleanly.
Note: Video requests always use queue.fal.run and are unaffected by this setting.
​
headers
array<string, string>
default:"[]"
An associative array of additional HTTP headers to merge into every outbound request alongside the Authorization: Key <api-key> header. Use this to attach tracing IDs, custom routing headers, or any other metadata required by your infrastructure or a fal.ai enterprise plan.
​
transcriptionPollTimeoutMs
int
default:"60000"
Maximum number of milliseconds the transcription model will wait for a job to reach a terminal state before throwing a timeout exception. The default of 60000 (60 seconds) is sufficient for most audio files. Increase this for very long recordings.
​
videoPollIntervalMs
int
default:"2000"
Milliseconds between successive status-check requests to queue.fal.run while waiting for a video generation job to complete. The default of 2000 (2 seconds) balances responsiveness against unnecessary API traffic. Reduce this if near-realtime feedback is critical; increase it to lower request volume for long-running models.
​
videoPollTimeoutMs
int
default:"300000"
Maximum number of milliseconds to wait for a video job to complete before throwing a timeout exception. The default of 300000 (5 minutes) covers most standard video generation models. Long-form or high-resolution models may require a larger value.

​
Complete example

The example below passes every available option to Fal::create(), which forwards them to FalOptions::fromArray(): 
<?php

use AiSdk\Fal;

$fal = Fal::create([
    'apiKey'                     => getenv('FAL_API_KEY'),
    'baseUrl'                    => 'https://fal.run',
    'headers'                    => ['X-Trace-Id' => 'abc123'],
    'transcriptionPollTimeoutMs' => 30_000,
    'videoPollIntervalMs'        => 3_000,
    'videoPollTimeoutMs'         => 120_000,
]);
If you are using a video generation model known to take longer than 5 minutes — such as high-resolution or long-form diffusion models — increase videoPollTimeoutMs to match the model’s expected completion time. For example, set it to 600_000 (10 minutes) or 900_000 (15 minutes) to avoid premature timeout exceptions.

Build docs developers (and LLMs) love

Get started for freeTalk to us