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 (class AiSdk\Fal\FalOptions) is the immutable configuration object passed to FalProvider. All constructor parameters are readonly. Use FalOptions::fromArray() to build one (called internally by Fal::create()), or construct one manually if you need to wire FalProvider directly.

​
Constants

ConstantValueDescription
DEFAULT_BASE_URL'https://fal.run'The default fal.ai REST API base URL.
PROVIDER_NAME'fal'The string identifier returned by FalProvider::name().

​
Constructor Parameters

public function __construct(
    public readonly string $apiKey,
    public readonly string $baseUrl = self::DEFAULT_BASE_URL,
    public readonly array  $headers = [],
    public readonly int    $transcriptionPollTimeoutMs = 60_000,
    public readonly int    $videoPollIntervalMs = 2000,
    public readonly int    $videoPollTimeoutMs = 300_000,
    public readonly ?Sdk   $sdk = null,
)
​
apiKey
string
required
Your fal.ai API key. When using FalOptions::fromArray(), this is resolved from $config['apiKey'] first, then the FAL_API_KEY environment variable.
​
baseUrl
string
default:"https://fal.run"
The API base URL. Any trailing slash is stripped automatically. When using FalOptions::fromArray(), this falls back to the FAL_BASE_URL environment variable before using the hardcoded default.
​
headers
array<string, string>
default:"[]"
Extra HTTP headers included in every request alongside the Authorization header. Useful for adding custom tracing or routing headers.
​
transcriptionPollTimeoutMs
int
default:"60000"
Maximum time in milliseconds to wait while polling for a transcription result before timing out.
​
videoPollIntervalMs
int
default:"2000"
How many milliseconds to wait between each poll when checking the status of a video generation job.
​
videoPollTimeoutMs
int
default:"300000"
Total millisecond timeout for a complete video generation job (defaults to 5 minutes). If this limit is exceeded, polling stops and an error is raised.
​
sdk
Sdk|null
default:"null"
An optional AiSdk\Support\Sdk instance used for internal SDK metadata. Typically omitted; set automatically when the SDK wires up the provider.

​
Methods

​
FalOptions::fromArray()

Static factory method that builds a FalOptions instance from an associative config array, falling back to environment variables for apiKey and baseUrl. 
public static function fromArray(array $config = []): self
​
config
array<string, mixed>
default:"[]"
Associative array of configuration values. All keys are optional when environment variables provide the required values. Accepts the same keys as the constructor: apiKey, baseUrl, headers, transcriptionPollTimeoutMs, videoPollIntervalMs, videoPollTimeoutMs, sdk.
​
return
FalOptions
A fully constructed, immutable FalOptions instance.
This is the preferred way to create a FalOptions instance and is called automatically by Fal::create().

​
authHeaders()

Returns the merged authorization header array used internally by all model classes when making HTTP requests. 
public function authHeaders(): array
​
return
array<string, string>
An array containing ['Authorization' => 'Key {apiKey}'] merged with any extra headers defined at construction time. Custom headers are appended after the authorization header.

​
Example

use AiSdk\Fal\FalOptions;

$options = FalOptions::fromArray([
    'apiKey'               => 'fal-abc123',
    'baseUrl'              => 'https://fal.run',
    'headers'              => ['X-Request-Id' => 'req-001'],
    'videoPollIntervalMs'  => 3_000,
    'videoPollTimeoutMs'   => 600_000,
]);

// Inspect the auth headers
print_r($options->authHeaders());
// ['Authorization' => 'Key fal-abc123', 'X-Request-Id' => 'req-001']

Build docs developers (and LLMs) love

Get started for freeTalk to us