Video
POST/v1/videos
One endpoint, three modes — which one you get depends only on which fields you pass alongside model/prompt.
Parameters
promptstringRequired for most models; optional for the one model with no text-to-video mode at all (fal/happy-horse, animates the image with no guidance if omitted).modelstringOptional, default "machgen/minimax-h3" (also the "auto" resolution). No auto-router for video yet — pin a slug from the catalog.duration_secsnumberOptional, default 4. Snapped to the nearest value the model actually supports; some models bill a fixed length regardless of what's requested.aspect_ratio / resolutionstringOptional. Combine to request a size — e.g. resolution: "720p" + aspect_ratio: "9:16". aspect_ratio is one of 16:9/9:16/1:1/4:3/3:4/21:9; resolution is a tier the specific model supports (varies per model — see its catalog entry). An unsupported combination is silently ignored (model default used), never a 400.height / widthintegerOptional. Explicit pixel dimensions — overrides aspect_ratio/resolution when given, same precedence as size on /v1/images.start_image_urlstringOptional — image-to-video. Public https:// URL or inline data:image/...;base64,... URI, animates that starting frame.input_referencesarrayOptional — reference-to-video. Up to 9 {"type":"image_url","image_url":{"url":...}} entries, model-dependent cap.input_video_references / input_audio_referencesarrayOptional, reference-to-video only. Same shape, video_url/audio_url — up to 3 each on supporting models.input_audio_urlstringOptional — single-file audio-to-video, LTX-2.5 only.input_video_urlstringOptional — video editing. A single URL to an existing clip to modify (not guide a new generation with, unlike input_video_references); requires a non-empty prompt describing the edit on every model except Kling v3.0 Motion Control (see next row), and is mutually exclusive with every other input field above on every model except that one. See Video editing.provider / failoverobjectOptional. Same provider-preference shape as chat's provider, plus a timeout-triggered hedge (failover.on_timeout_sec) that resubmits to the next-cheapest untried host — both attempts get billed.
Motion control exception: novita/kling-motion-control-{std,pro}
are the one case on this platform where start_image_url combines with
a reference field — either input_video_references (one entry, fixed ~4s
output) or input_video_url (output matches the reference video's own
length, up to 30s) — and neither orientation requires prompt. See
Motion control for both worked examples.
Example response (202, job just created)
{
"id": "video_...",
"status": "queued",
"data": null,
"error": null,
"provider": "fal"
}Billed once, in full, at creation time from the requested/snapped duration_secs — polling is free. Exact extra fields (e.g. seconds, size, fallback_used) vary a little by which provider actually served the job.
GET/v1/videos/models
Unbilled. Live list of every valid model slug for POST /v1/videos — bare ids only, no price or capability breakdown (see /models for that).
Example response
{
"object": "list",
"data": [
{ "id": "machgen/minimax-h3", "object": "model" },
{ "id": "veo-3.1", "object": "model" },
{ "id": "kling-video-v3-omni", "object": "model" }
]
}GET/v1/videos/{id}
Unbilled — the full cost was already charged at creation time.
Parameters
idstring (path)The id returned by POST /v1/videos.Example response (status: "completed")
{
"id": "video_...",
"status": "completed",
"data": [{ "url": "https://..." }],
"error": null
}status is one of queued → in_progress → completed/failed. On failure, error carries the provider's message and data is null.