Video

Video generation routes are model-specific and often asynchronous. Treat response shape as upstream/model-defined unless a OneRouter page states otherwise.

POSThttps://onerouter.com/v1/videos

Troubleshooting

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

ParameterTypeRequiredDescription
Authorizationstring · requiredrequiredBearer token, formatted as `Bearer YOUR_API_KEY`.
Content-Typestring · requiredrequiredMust be `application/json`.

Routes

ParameterTypeRequiredDescription
/v1/videosPOSToptionalProvider-compatible video job submission when supported upstream.
/v1/videos/{job_id}GEToptionalPoll a video job when the upstream response provides a compatible job ID.
/v1/videos/*ANYoptionalOther 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:

ParameterTypeRequiredDescription
modelstringrequiredVideo model ID, e.g. a Veo/Sora/Kling-class model.
promptstringrequiredText description of the video to generate.
image_urlstringoptionalReference/first-frame image for image-to-video models.
durationintegeroptionalClip length in seconds (model-dependent).
sizestringoptionalResolution 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.

StatusDescription
pendingQueued, waiting to start.
processingActively generating.
completedFinished; the result URL(s) are available.
failedGeneration 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.