Authorization: Bearer or x-api-key), and the same per-client
rate limits and spend caps apply.
POST /v1/videos/generations— submit a job. Answers 202 with a job object containing anid.GET /v1/videos/generations/{id}— poll the job until itsstatusis terminal (succeededorfailed).
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.urlis 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_atandupstream_deleted_atreport platform-scheduled deletion of the provider-side artifact where a model supports it; they arenullfor models without platform-side deletion — including every model in the table below. - Extra metadata in
resultvaries by model (for examplewan-2.6echoes width/height/duration;seedance-2.0omits them). - On failure,
erroris a human-readable string andresultstaysnull.
Models & pricing
Image-to-video and reference-to-video (fal)
These models start from your media instead of a bare prompt: passimage
(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-secondwan-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: 400invalid_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 submit —
duration_secondsis not one of the values the model supports (for examplewan-2.6only 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_foundon 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).