Videos

Generate videos from text prompts or images. Video generation can take several minutes, so the SDK supports both synchronous and asynchronous modes.

Basic Usage

result = client.videos.generate(
    model="fal-ai/veo3",
    prompt="waves crashing on a beach",
    image_url=None,         # optional: image URL to animate
    duration_seconds=5.0,   # default 5.0
    params=None,            # model-specific parameters
)
 
print(result.video_url)

Async Mode (Recommended)

Video generation can take several minutes. To avoid 502 timeouts from your proxy or CDN, use async mode.

Video generation in Python may be asynchronous by default. Check video_url to see if the video is ready, or use the async client:

async with AsyncClient() as client:
    result = await client.videos.generate(
        model="fal-ai/veo3",
        prompt="a bird flying",
        duration_seconds=6.0,
    )
    print(result.video_url)

Model Presets (JavaScript)

The JavaScript SDK exports VIDEO_MODEL_PRESETS for common provider model IDs:

import { VIDEO_MODEL_PRESETS } from "@visgate_ai/client";
 
// Use presets or pass a model string directly
await client.videos.generate(VIDEO_MODEL_PRESETS.fal, "a sunset");
await client.videos.generate("fal-ai/veo3", "a sunset");
await client.videos.generate("runway/gen4_turbo", "a sunset");

Image-to-Video

Pass an imageUrl to animate an existing image:

result = client.videos.generate(
    model="fal-ai/veo3",
    prompt="gentle camera pan",
    image_url="https://example.com/photo.jpg",
    duration_seconds=5.0,
)

VideoResult Properties

Property	Python	JavaScript	Type	Description
ID	`result.id`	`result.id`	`string`	Request ID
Video URL	`result.video_url`	`result.videoUrl`	`string \| None`	Generated video URL
Model	`result.model`	`result.model`	`string`	Model identifier
Provider	`result.provider`	`result.provider`	`string`	Provider name
Cost	`result.cost`	`result.cost`	`float` / `number`	Cost in USD
Cache hit	`result.cache_hit`	`result.cacheHit`	`bool` / `boolean`	Served from cache?
Latency	`result.latency_ms`	`result.latencyMs`	`int \| None` / `number`	Latency in ms
Created at	`result.created_at`	`result.createdAt`	`datetime` / `string`	Timestamp

Async Request Status

After starting an async generation, poll the request status:

const status = await client.requests.get(result.requestId);
// status.status: "pending" | "processing" | "completed" | "failed"
// status.outputUrl: the video URL when completed