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.

Video generation with fal.ai is asynchronous. FalVideoModel submits a job to https://queue.fal.run/{modelId} and then polls response_url at a configurable interval until the video is ready or the timeout is exceeded. The SDK manages the entire polling loop inside run(), so your code only receives a VideoJob once the job has either succeeded or failed.

​
Basic Usage

use AiSdk\Generate;
use AiSdk\Fal;

$result = Generate::video()
    ->model(Fal::model('fal-ai/kling-video/v1/standard/text-to-video'))
    ->prompt('A sunrise over misty mountains.')
    ->run();

// Polling is handled automatically; $result->video->url is ready when run() returns
echo $result->video->url;

​
How It Works

Video generation follows a two-step asynchronous flow:
  1. Submit — generate() sends a POST to https://queue.fal.run/{modelId} with the request body. fal.ai queues the job and responds immediately with a request_id and a response_url. A VideoJob with status Queued is returned.
  2. Poll — poll() sends a GET to response_url on each tick. When the response contains a video.url, the job transitions to Succeeded and a complete VideoJob is returned with the VideoData populated. While the video is still being rendered, poll() returns a VideoJob with status Running.
Both steps are called automatically by the SDK’s run loop; you do not need to invoke generate() or poll() directly.

​
VideoJob Status Values

StatusMeaning
QueuedThe job has been submitted and is waiting to be picked up by the fal.ai worker.
RunningThe worker has started generating the video; polling is ongoing.
SucceededThe video is ready; $job->video->url contains the download URL.
FailedAn error occurred; $job->errorMessage describes the problem.

​
Request Parameters

The following fields are sent as JSON to queue.fal.run:
FieldTypeDescription
promptstringThe text prompt describing the video to generate.
image_urlstring (optional)A URL to use as the first frame. Only included when $request->image is a URL source.
Additional fields from $request->providerOptionsFor('fal') are merged into the body last. 
$result = Generate::video()
    ->model(Fal::model('fal-ai/kling-video/v1/standard/text-to-video'))
    ->prompt('A sunrise over misty mountains.')
    ->providerOptions('fal', ['duration' => '5', 'cfg_scale' => 0.5])
    ->run();

​
Response

A completed VideoJob (status Succeeded) carries a video property of type VideoData:
  • url (string) — the publicly accessible URL of the generated video, taken from video.url in the fal.ai queue response.
  • mimeType (string) — taken from video.content_type; defaults to video/mp4 when the API omits it.
echo $result->video->url;      // https://cdn.fal.ai/…
echo $result->video->mimeType; // video/mp4

​
Configuring Timeouts

Use videoPollIntervalMs and videoPollTimeoutMs in the Fal::create() configuration array to tune how aggressively the SDK polls and how long it waits before giving up: 
Fal::create([
    'apiKey'               => getenv('FAL_API_KEY'),
    'videoPollIntervalMs'  => 3_000,   // poll every 3 seconds
    'videoPollTimeoutMs'   => 600_000, // wait up to 10 minutes
]);
The defaults are 2,000 ms (2 seconds) for the interval and 300,000 ms (5 minutes) for the timeout.
If the initial queue response from fal.ai does not include a response_url, poll() cannot proceed and immediately returns a VideoJob with status Failed and an errorMessage of "fal queue response did not include response_url." — no polling is attempted.
FalVideoModel always posts to https://queue.fal.run/{modelId} regardless of the baseUrl value configured in FalOptions. The baseUrl setting applies only to synchronous endpoints (image, speech, transcription). Video always uses the fal.ai queue.

Build docs developers (and LLMs) love

Get started for freeTalk to us