Video
Video generation routes are model-specific and often asynchronous. Treat response shape as upstream/model-defined unless a OneRouter page states otherwise.
https://onerouter.com/v1/videosTroubleshooting
Errors carry an HTTP status and a JSON error body. See Errors & Retries for the full list.
Asynchronous & model-defined
Video generation runs as a background job and the exact response shape is defined by the upstream model — OneRouter does not expose a universal /v1/tasks/{id} API. Follow the fields the model returns, and download result URLs promptly: provider links can expire.
Supported models
Use a video model ID (Veo / Sora / Kling / Seedance class). See the Video Models page for current options and how each one is billed.
Overview
Video generation is asynchronous: you submit a prompt (and optionally a first-frame image), receive a job ID, and poll until the job is completed, then download the returned clip. Because providers differ, the exact request and response fields come from the selected model — the shapes below are the common pattern, not a fixed OneRouter contract.
Request headers
| Parameter | Type | Required | Description |
|---|---|---|---|
| Authorization | string · required | required | Bearer token, formatted as `Bearer YOUR_API_KEY`. |
| Content-Type | string · required | required | Must be `application/json`. |
Routes
| Parameter | Type | Required | Description |
|---|---|---|---|
| /v1/videos | POST | optional | Provider-compatible video job submission when supported upstream. |
| /v1/videos/{job_id} | GET | optional | Poll a video job when the upstream response provides a compatible job ID. |
| /v1/videos/* | ANY | optional | Other video routes may be forwarded to upstream providers. |
Common request fields
Exact fields are defined by the selected model. The most common video-generation fields look like this:
| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | required | Video model ID, e.g. a Veo/Sora/Kling-class model. |
| prompt | string | required | Text description of the video to generate. |
| image_url | string | optional | Reference/first-frame image for image-to-video models. |
| duration | integer | optional | Clip length in seconds (model-dependent). |
| size | string | optional | Resolution or aspect ratio, e.g. `1280x720` or `16:9`. |
Task lifecycle
When a model runs as a background job, you submit a request, receive a task/job ID, then poll until the status is terminal. The exact field names come from the upstream model.
| Status | Description |
|---|---|
| pending | Queued, waiting to start. |
| processing | Actively generating. |
| completed | Finished; the result URL(s) are available. |
| failed | Generation failed; inspect the error fields. |
Billing
Video models are commonly billed by duration, resolution, quality tier, generated clip count, or model-specific units. Review the current model price and estimated request volume before starting large batches.