Skip to content
Router One
Sign up
Skip to content
Router One
Videos

Submit Video Generation

Submit an async video generation task — returns 202 Accepted with a task_id to poll; generation takes 30 seconds to several minutes depending on the model. The flow:

  1. Call this endpoint to submit the task; on success, returns 202 Accepted with a task_id.
  2. Use the task_id with GET /v1/videos/generations/{task_id} to poll the status.
  3. When status becomes completed, read the video url from the response.

Recommended: poll at intervals of at least 3 seconds; do not set an HTTP timeout for the whole generation flow — only set short timeouts (e.g. 30 s) for individual submit/poll requests.

Clip length and resolution are fixed per model and priced per clip; duration / size in the request body are ignored. The video generation page shows whether a video model is listed — none is as of 2026-10-01.

Reference image: image_url is required by image-to-video models (exactly one image) and rejected by text-to-video models. It accepts an HTTP(S) URL up to 20 MB; after submission Router One downloads and re-hosts it securely, so even short-lived user-uploaded URLs work.

Full reference for every endpoint: Markdown · OpenAPI 3.1 JSON

POST
/v1/videos/generations

Authorization

AuthorizationBearer <token>

Authenticate with your API Key. Get your API Key in the Router One console; the format is sk-xxx.

In: header

Request Body

modelstring

Model ID. Choose a model that supports video generation; check the console model marketplace.

promptstring

Text prompt for video generation, describing scene content, camera motion, style, etc.

duration?integer

Ignored by the video models listed before 2026-09-05, each of which produced one fixed clip length (see the video generation page); no video model is listed as of 2026-10-01. Kept for forward compatibility.

size?string

Ignored by the video models listed before 2026-09-05 (resolution was fixed per model and priced per clip); no video model is listed as of 2026-10-01. Kept for forward compatibility.

aspect_ratio?string

Video aspect ratio. 16:9 for landscape, 9:16 for portrait short video, 1:1 for social-style square. Whether it is honored is decided per video model; no video model is currently listed, so check the model page before relying on it.

Value in"16:9" | "9:16" | "1:1"
negative_prompt?string

Negative prompt — elements to avoid in the output. Optional; the video models listed before 2026-09-05 ignored it, and no video model is listed as of 2026-10-01.

image_url?string

Reference image URL. Required by image-to-video models (exactly one image); text-to-video models reject it with 400 <model> is text-to-video only: image_url is not supported. Must be HTTP(S) reachable; up to 20 MB. Router One downloads and securely re-hosts it.

Formaturi
image_urls?array<string>

Multi-reference image URLs. No currently listed model accepts more than one reference image — sending several returns 400 <model> accepts exactly one image_url. Kept for forward compatibility; same per-image constraints as image_url.

Itemsitems <= 3
input_reference?string

Model-specific reference input identifier. Only used when the selected model explicitly requires it; it is treated as a reference image, so the same model rules as image_url apply.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.router.one/v1/videos/generations" \  -H "Content-Type: application/json" \  -d '{    "model": "<text-to-video-model-id>",    "prompt": "Waves lapping at the shore, dusk sunlight glittering on the water, slow motion",    "aspect_ratio": "16:9"  }'
{
  "task_id": "v_8f3a92c1d4e74b6ea0b5f1d29c7e8a01",
  "status": "pending"
}
{
  "error": {
    "message": "reference image exceeds 20MB",
    "type": "invalid_request_error",
    "code": "INVALID_REQUEST",
    "request_id": "290dd478f91d8aec68f7535e871376eb"
  }
}
{
  "error": {
    "message": "invalid api key",
    "type": "authentication_error",
    "code": "AUTH_INVALID_API_KEY",
    "request_id": "290dd478f91d8aec68f7535e871376eb"
  }
}

{
  "error": {
    "message": "insufficient balance: top up at https://router.one/deposit",
    "type": "billing_error",
    "code": "INSUFFICIENT_BALANCE",
    "request_id": "290dd478f91d8aec68f7535e871376eb"
  }
}

{
  "error": {
    "message": "rate limit exceeded",
    "type": "rate_limit_error",
    "code": "RATE_LIMIT_EXCEEDED",
    "request_id": "290dd478f91d8aec68f7535e871376eb"
  }
}
{
  "error": {
    "message": "empty response from upstream",
    "type": "api_error",
    "code": "INTERNAL_ERROR",
    "request_id": "290dd478f91d8aec68f7535e871376eb"
  }
}
{
  "error": {
    "message": "provider is currently unavailable",
    "type": "service_unavailable",
    "code": "PROVIDER_UNAVAILABLE",
    "request_id": "290dd478f91d8aec68f7535e871376eb"
  }
}
{
  "error": {
    "message": "upstream timeout",
    "type": "service_unavailable",
    "code": "PROVIDER_UNAVAILABLE",
    "request_id": "290dd478f91d8aec68f7535e871376eb"
  }
}

Get Video Generation Status GET

Previous page