Skip to main content
POST
Video API workflow
All FreeModel video routes use the same asynchronous workflow. Choose a model from the Video Series sidebar, submit a request, save the returned id, and poll until the task completes. The model page defines the accepted duration, aspect ratio, resolution, image-reference, and source-video rules. Do not send values from one model family to another.
string
required
An available video model ID. Choose one from the Video Series pages and confirm it with GET /v1/models.
string
required
Describe the subject, action, camera movement, lighting, and audio intent.
string
A duration listed on the model page. If you omit it, the task runs for 10 seconds, or for the model’s shortest length when 10 isn’t offered. Models whose length follows a source clip (gemini-omni-extend, gemini-omni-flash-1.1-extend) reject seconds.
string
Gemini Omni (gemini-omni-*) only: 1280x720, 720x1280, 1920x1080, or 1080x1920.
string
Every other video model, for example 16:9, 9:16, or adaptive. Use the values listed on the model page and do not send size with it.
string
Output tier for models that sell several resolutions: Seedance 2.0, Seedance 2.5 mode models, and Gemini Omni Flash 1.1. The price depends on it.
string[]
Public http or https image URLs when the selected model accepts them. Follow its required count and per-image size limit.
string
One public source-video URL for models with a single video input, such as Gemini Omni Extend, MiniMax H3, and the Seedance 2.5 -v2v SKUs.
string[]
Up to three public clips for Seedance reference-to-video (*-r2v) and seedance-2.5-extend.
string[]
Up to three public reference audio URLs for Seedance *-r2v models.
Models that bill reference or source video seconds (Seedance *-r2v, seedance-2.5-extend, and the Seedance 2.5 -v2v SKUs) bill output seconds plus the length of the clips you send. The gateway measures each MP4 or MOV clip itself by reading its header with HTTP range requests, so host clips where range requests work, such as S3, R2, or most CDNs. A clip that cannot be measured is billed at the model’s maximum reference length.
boolean
Seedance models: set to false for a silent video.
string
Optional public https URL. When the task reaches a final state, the gateway sends it one signed event with the task under data.task. See Task webhooks.
string
Required with webhook: 16 to 256 characters, used to sign the delivery.

Submit a task

Poll and download

Include the same model query value while polling and downloading.
Poll every 10 to 20 seconds while status is queued or in_progress. Download only after status becomes completed.

Task status API

Query the normalized task record and final media URLs.

Webhooks

Receive the final task result without continuous polling.