> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routerbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Video Generation

> Async video generation. Submit a job, then poll by id (or supply a callback_url).

## Endpoints

```
POST https://routerbase.com/v1/videos/generations
GET  https://routerbase.com/v1/videos/generations/{id}
```

Video generation is **asynchronous**. The `POST` returns immediately with an `id` and `status: "pending"`. Retrieve the result by polling `GET /v1/videos/generations/{id}` or by setting a `callback_url`.

## Request Headers

| Header          | Value                       |
| --------------- | --------------------------- |
| `Authorization` | `Bearer sk-rb-xxxxxxxxxxxx` |
| `Content-Type`  | `application/json`          |

## Request Body (POST)

<ParamField body="model" type="string" required>
  Video model ID. e.g. `bytedance/seedance-2-0`, `kuaishou/kling-2-1`, `minimax/hailuo-pro`, `alibaba/wan-2-7-t2v`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Text description of the video.
</ParamField>

<ParamField body="duration" type="number">
  Duration in seconds. Model-dependent (commonly `5`, `8`, `10`).
</ParamField>

<ParamField body="aspect_ratio" type="string">
  e.g. `16:9`, `9:16`, `1:1`.
</ParamField>

<ParamField body="resolution" type="string">
  e.g. `720p`, `1080p`. Model-dependent.
</ParamField>

<ParamField body="image_urls" type="array">
  Required for image-to-video models (`*-i2v`, `*-image-to-video`). Each entry may be a public HTTPS URL **or** an inline base64 `data:` URI (e.g. `data:image/png;base64,…`) — inline images are decoded and hosted automatically. For anything larger than a few MB, prefer uploading via `POST /v1/uploads` and passing the returned URL.
</ParamField>

<ParamField body="callback_url" type="string">
  Optional. RouterBase will `POST` the final result to this HTTPS URL when the task completes. See [Async Tasks → Callback](/essentials/async-tasks#option-2-callback-url).
</ParamField>

## Submit a Job

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://routerbase.com/v1/videos/generations \
    -H "Authorization: Bearer sk-rb-xxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "bytedance/seedance-2-0",
      "prompt": "A cat playing piano in a sunny living room",
      "duration": 8,
      "aspect_ratio": "16:9"
    }'
  ```

  ```python Python theme={null}
  import requests

  r = requests.post(
      "https://routerbase.com/v1/videos/generations",
      headers={"Authorization": "Bearer sk-rb-xxxxxxxxxxxx"},
      json={
          "model": "bytedance/seedance-2-0",
          "prompt": "A cat playing piano in a sunny living room",
          "duration": 8,
          "aspect_ratio": "16:9",
      },
  )
  print(r.json()["id"])
  ```
</CodeGroup>

### Response (POST)

```json theme={null}
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "object": "video.generation",
  "status": "pending",
  "model": "bytedance/seedance-2-0",
  "created": 1776245700
}
```

## Poll Status (GET)

```
GET /v1/videos/generations/{id}
```

```python theme={null}
import time, requests

def wait_for_video(gen_id, api_key, interval=3, timeout=600):
    headers = {"Authorization": f"Bearer {api_key}"}
    url = f"https://routerbase.com/v1/videos/generations/{gen_id}"
    elapsed = 0
    while elapsed < timeout:
        s = requests.get(url, headers=headers).json()
        if s["status"] == "success":
            return s["data"][0]["url"]
        if s["status"] == "failed":
            raise RuntimeError(f"Generation failed")
        time.sleep(interval)
        elapsed += interval
    raise TimeoutError("Generation timed out")
```

### Response (GET)

While running:

```json theme={null}
{
  "id": "f47ac10b-...",
  "object": "video.generation",
  "status": "pending",
  "model": "bytedance/seedance-2-0",
  "created": 1776245700
}
```

When complete:

```json theme={null}
{
  "id": "f47ac10b-...",
  "object": "video.generation",
  "status": "success",
  "model": "bytedance/seedance-2-0",
  "data": [
    { "url": "https://media.routerbase.com/media/<user>/<gen>/0.mp4" }
  ],
  "created": 1776245700
}
```

| `status`  | Meaning                                        |
| --------- | ---------------------------------------------- |
| `pending` | Task is queued or running                      |
| `success` | Generation complete; `data[].url` is populated |
| `failed`  | Generation failed                              |

## Image-to-video

For i2v models (e.g. `kuaishou/kling-v2-1-master-i2v`, `bytedance/bytedance-v1-pro-i2v`), include `image_urls`:

```json theme={null}
{
  "model": "kuaishou/kling-v2-1-master-i2v",
  "prompt": "Camera slowly zooms out",
  "image_urls": ["https://example.com/source.jpg"],
  "duration": 5
}
```