---
title: Generate a video
description: Create a video job with any model on the Video Router.
---
`POST` `/v1/video-router/generate`

**Host** `https://api.open.sume.com` · **Auth** API key

Starts a video job with the model you name and returns at once. Video takes from about a minute to several, so a [webhook](/docs/webhooks) is usually better than tight polling.

## Request

### Headers

| Header | Type | Required | Description |
|---|---|---|---|
| `Authorization` | string | Yes | `Bearer <key>`. Or send `x-api-key`. |
| `Content-Type` | string | Yes | `application/json` |
| `Idempotency-Key` | string | No | 1–255 printable ASCII. Makes a retry return the original job. See [Idempotency](/docs/idempotency). |

### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `model` | string | Yes | An id from [List video models](/docs/reference/video/list-models), such as `seedance-2.5` or `kling-3`, or `auto` to let Sume pick. |
| `prompt` | string | Usually | What happens in the shot. Optional on `auto` and on a few edit models. |
| `duration` | integer | No | Seconds. Each model lists its range in `capabilities.duration_seconds` (`seedance-2.5`: 4–30). |
| `resolution` | string | No | One the model lists, such as `480p`, `720p`, `1080p`. |
| `aspect_ratio` | string | No | `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, `auto` or `adaptive`, where listed. |
| `image_url` | string | No | First frame (HTTPS) for image-to-video. |
| `end_image_url` | string | No | Last frame. Needs `image_url`. |
| `video_url` | string | No | Source clip for video-to-video models. |
| `audio_url` | string | No | Speech for lip-sync models. |
| `reference_image_urls` | string[] | No | 1–10 reference images, where the model takes them. |
| `reference_video_urls` | string[] | No | 1–5 reference clips, where the model takes them. |
| `generate_audio` | boolean | No | Ask for a soundtrack, on models that make one. |
| `mode` | string | No | `async` (default), `webhook`, `sync` or `subscribe`. See [How the API works](/docs/how-it-works). |
| `webhook_url` | string | No | Public HTTPS URL for the terminal callback. Used with `mode: "webhook"`. |
| `wait_timeout_seconds` | integer | No | 0–30. How long `sync` / `subscribe` waits before answering. |
| `metadata` | object | No | Your own key-value data, stored on the job. Not sent to the model. |

## Example

<!-- api-call-example:v2-video-generate -->

## Response

`202 Accepted`

The response has the same shape as [Generate an image](/docs/reference/images/generate#response): `request_id`, the `job` (with `type: "video_generation"`), and `status_url`, `result_url`, `cancel_url`, `next_poll_after_seconds`.

```json
{
  "data": {
    "request_id": "job_...",
    "job": {
      "id": "job_...",
      "type": "video_generation",
      "status": "queued",
      "model": "seedance-2.5"
    },
    "status_url": "https://api.open.sume.com/v1/jobs/job_.../status",
    "result_url": "https://api.open.sume.com/v1/jobs/job_.../result",
    "next_action": "poll_status",
    "next_poll_after_seconds": 2,
    "terminal": false
  }
}
```

## Errors

| Status | `code` | When |
|---|---|---|
| 400 | `invalid_request` | A field is missing, unknown for the model, or out of range. |
| 400 | `concurrency_limit_reached` | Your workspace is at its jobs-in-flight cap. |
| 401 | `unauthorized` | No key, or the key is wrong or revoked. |
| 402 | `insufficient_funds` | Your balance cannot cover the price. `details` has `required_usd` and `available_usd`. |
| 409 | `idempotency_conflict` | The `Idempotency-Key` was used for a different request. |
| 429 | `rate_limited` | Too many requests for your key in this window. |
| 503 | `database_busy` | A short overload. Retry after `retry-after`. |

[All error codes](/docs/errors)

## Related

- [List video models](/docs/reference/video/list-models)
- [Webhooks](/docs/webhooks)
- [Estimate a price](/docs/reference/catalog/estimate)