Video Tool

Video Generation

Generate a video from a text prompt, or animate a photo into one. Unlike every other Skill, this is submit-then-poll: a generation takes minutes, not seconds, so the call that starts it returns immediately and you read the result from a second endpoint once it lands.

Submit

POST /v1/video/generations

curl https://api.router9.com/v1/video/generations \
  -H "Authorization: Bearer sk-r9k-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A small paper boat gently floating down a calm stream",
    "duration_seconds": 6,
    "resolution": "720p",
    "ratio": "16:9"
  }'

Parameter	Type	Required	Description
`prompt`	string	Yes	What the video should show, or how a supplied photo should move
`model`	string	No	Override the default video model (must be allowlisted)
`image_url`	string	No	An HTTP(S) URL or `data:` URL used as the first frame. Omit for text-to-video
`duration_seconds`	integer	No	Clip length. Range varies by model — see the catalog below
`resolution`	string	No	A vendor-specific tier, e.g. `720p`, `2K`. Varies by model
`ratio`	string	No	Aspect ratio, e.g. `16:9`, `9:16`. Varies by model

Duration, resolution and ratio vocabularies are per model, not fixed across the tool — one vendor's 2K is another's 1080p, and not every model accepts a reference photo. Call GET /v1/public/video-models to see what the model you are using actually offers before you submit.

Response

202 Accepted — the job is queued, not finished:

{
  "id": "cjunazub3ojykjbwoqm11b6sq",
  "status": "QUEUED",
  "model": "bytedance/seedance-2.0-mini",
  "queuedAt": "2026-09-12T11:39:27.565Z"
}

Nothing is billed at submit time. The generation is only charged once it actually succeeds — see Credits.

Poll

GET /v1/video/jobs/{id}

curl https://api.router9.com/v1/video/jobs/cjunazub3ojykjbwoqm11b6sq \
  -H "Authorization: Bearer sk-r9k-your-key"

status is one of QUEUED, SUBMITTED (accepted by the vendor and running), SUCCEEDED, FAILED, or CANCELLED. Poll every few seconds until it reaches one of the last three.

{
  "id": "cjunazub3ojykjbwoqm11b6sq",
  "status": "SUCCEEDED",
  "model": "bytedance/seedance-2.0-mini",
  "queuedAt": "2026-09-12T11:39:27.565Z",
  "startedAt": "2026-09-12T11:39:27.601Z",
  "finishedAt": "2026-09-12T11:43:03.545Z",
  "resultUrl": "https://.../generated-media/...",
  "resultExpiresAt": "2026-09-13T11:43:03.545Z"
}

resultUrl is a signed link, present only once status is SUCCEEDED — absent on every other status, and gone again after resultExpiresAt. Download it before then; a new poll after expiry does not mint a fresh one for an already-terminal job. A FAILED or CANCELLED job carries an error string instead.

Catalog

GET /v1/public/video-models   → { "models": [...] }

Public. Each model carries a constraints block — whether it accepts a reference photo, its duration range, and the resolutions and ratios it actually offers — so a client can discover a limit without having to be refused by it.

Errors

Every video endpoint answers failures in the shared media error envelope. See Errors.

Credits

Video Skill calls consume credits from your plan's monthly credit allowance — the same allowance used for chat completions. Video is metered per second of finished clip, at a rate that can vary by resolution — a model's higher tiers cost more per second than its default. See Credits & Usage and Tool Usage & Credits.