Skip to main content
This section is about creating video from a text prompt. To send an existing video to a model for analysis, see Video input. The gateway generates video too. Unlike image generation, video is asynchronous: a generation can take from tens of seconds to several minutes, so you submit a job and poll for its result instead of holding one HTTP request open. Authentication is the same API key as every other route (as Authorization: Bearer or x-api-key), and the same per-client rate limits and spend caps apply.
  1. POST /v1/videos/generations — submit a job. Answers 202 with a job object containing an id.
  2. GET /v1/videos/generations/{id} — poll the job until its status is terminal (succeeded or failed).

Quickstart

Request parameters

Media inputs

Image-to-video-capable models accept media inputs alongside (or instead of) the prompt. The models in the public table below are text-to-video only — they reject every field in this section synchronously with a 400 naming the unsupported fields, so nothing is ever silently ignored. Media-capable models are provisioned per account; if yours has one, these fields apply:
Inline media and retries. Requests that pass images inline (data URI or bare Base64) are not re-submitted automatically after a transient provider rejection — the job fails with a clear message and you should submit again. Passing media by URL keeps automatic submit retries. Inline payloads are never persisted in stored job records, and once a job reaches a terminal state the platform scrubs the stored request content — prompt, generation parameters, media URLs — down to billing metadata (zero content retention; scrubbing is deferred while an organization’s optional support-capture window is open). The job stays readable by id: status, result, and error are unaffected.

The job object

Both endpoints return the same shape — object is always "video.generation.job" and status moves strictly forward: A finished job looks like this:
  • On success, result.video.url is an MP4 hosted on the provider’s CDN — download promptly and persist on your side; the URL is not permanent.
  • Generated artifacts follow each provider’s own retention policy — no fixed deletion window is guaranteed (see the provider data-handling page for per-provider retention). artifact_expires_at and upstream_deleted_at report platform-scheduled deletion of the provider-side artifact where a model supports it; they are null for models without platform-side deletion — including every model in the table below.
  • Extra metadata in result varies by model (for example wan-2.6 echoes width/height/duration; seedance-2.0 omits them).
  • On failure, error is a human-readable string and result stays null.

Models & pricing

Image-to-video and reference-to-video (fal)

These models start from your media instead of a bare prompt: pass image (or first_frame) for image-to-video, or reference_images for reference-to-video, alongside the prompt. They are served by fal in the United States and billed per second of finished video at fal’s list price (plus the small per-input-image fee where fal charges one). Video-to-video utilities on fal (reframe, upscale, translate, prompt-driven edit, background removal) bill per second of the source clip and are provisioned per account — they are not in the public model list. Video is billed per second of finished video at the tier actually generated — a 5-second wan-2.6 clip at 720p is roughly $0.50. Only videos that finish successfully are billed. Each job’s cost is metered against your key exactly like chat and image traffic, appears in your usage reporting, and counts toward the same spend caps.

Polling from Python

A production-shaped loop with a hard deadline: poll every few seconds, treat 5xx poll errors as transient (the job keeps running server-side), and give up after a sensible timeout. A typical 5-second wan-2.6 clip completes in under a minute; longer clips and higher tiers take proportionally longer.
SDK note. The SDKs do not yet ship a video-generation helper — call the HTTP endpoints directly as above. Typed helpers in all five languages are coming in an upcoming SDK release.

Errors

Submission errors reuse the familiar codes: 400 invalid_request_error for a malformed body, 401 invalid_api_key, 402 usage_cap_exceeded when a spend cap is reached, and 429 rate_limit_exceeded with a Retry-After header. Three video-specific cases:
  • 400 at submitduration_seconds is not one of the values the model supports (for example wan-2.6 only accepts 5, 10, or 15). The message lists the allowed values; no job is created.
  • 502 at submit — the provider rejected the job synchronously (for example a prompt rejected by upstream validation). The response carries the provider’s message and a job_id; the failed job remains readable by id.
  • 404 job_not_found on poll — the job id is unknown or belongs to a different workspace’s key.
Content policy. Upstream video providers apply safety filtering to prompts and outputs. A prompt that violates the provider’s content policy fails the generation — the job lands in failed with the provider’s message in error (or, if rejected at submit, in the 502 response).