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.

Every HTTP request made by aisdk/fal — whether to fal.run for image, speech, or transcription, or to queue.fal.run for video — includes an Authorization header generated by FalOptions::authHeaders(). The header value follows the Key <api-key> scheme required by fal.ai’s REST API. No OAuth flow, token exchange, or session management is involved: the raw API key is sent on each request.

​
Obtaining an API key

Create a free account at fal.ai and navigate to your dashboard to generate an API key. Keys are prefixed with fal- by convention. Treat them as secrets — anyone who holds a key can make requests billed to your account.

​
Supplying the key

There are three ways to provide your API key to the provider, listed in recommended order:

​
1. Environment variable FAL_API_KEY (preferred)

Set the variable in your shell, .env file, or deployment environment. The provider reads it automatically when Fal::default() or Fal::create() is called with no apiKey key. 
export FAL_API_KEY=fal-...

​
2. Fallback environment variable FAL_KEY

If FAL_API_KEY is not set, the provider falls back to FAL_KEY. This matches the naming convention used by the upstream JavaScript @ai-sdk/fal package and can be useful when sharing environment configuration across runtimes. 
export FAL_KEY=fal-...

​
3. Programmatic via Fal::create()

Pass the key directly in the config array. This is useful when fetching keys from a secrets manager at runtime, or when you need more than one provider instance with different keys. 
<?php

use AiSdk\Fal;

$fal = Fal::create([
    'apiKey' => 'fal-...',
]);

​
Authorization header format

Once the key is resolved, FalOptions::authHeaders() produces the following header, which is merged into every outbound request: 
Authorization: Key fal-...
The full header map returned by authHeaders() looks like this when no extra headers are configured: 
[
    'Authorization' => 'Key fal-...',
]

​
Custom extra headers

You can attach additional HTTP headers to every request by supplying a headers array in the config. These are merged with the Authorization header by authHeaders() — they do not replace it. 
<?php

use AiSdk\Fal;

$fal = Fal::create([
    'apiKey'  => getenv('FAL_API_KEY'),
    'headers' => [
        'X-Custom-Header' => 'my-value',
        'X-Trace-Id'      => 'abc123',
    ],
]);
The resulting header map sent with each request will be: 
[
    'Authorization'   => 'Key fal-...',
    'X-Custom-Header' => 'my-value',
    'X-Trace-Id'      => 'abc123',
]
If a key in headers collides with Authorization, the headers value will take precedence because array_merge places it after the built-in entry — avoid overriding Authorization unless you know what you are doing.
Never hardcode API keys in source code. Committing a key to version control exposes it to anyone with repository access and makes rotation painful. Use environment variables, a secrets manager (such as AWS Secrets Manager, HashiCorp Vault, or Laravel’s encrypted .env), or inject keys at deploy time through your CI/CD pipeline.

Build docs developers (and LLMs) love

Get started for freeTalk to us