# Unified video API

https://video-doc.1route.dev/en/docs/video-api



## Endpoints [#endpoints]

Use `https://video.1route.dev` with a site video key in `Authorization: Bearer YOUR_API_KEY`. Create requests use JSON.

[Complete OpenAPI](/openapi.json) · [All 38 public models](/video-models.json)

| Operation                   | Method and path                        |
| --------------------------- | -------------------------------------- |
| Models allowed for your key | `GET /v1/models`                       |
| Create one video task       | `POST /v1/videos`                      |
| Retrieve the same task      | `GET /v1/videos/{id}`                  |
| Download / inspect headers  | `GET` / `HEAD /v1/videos/{id}/content` |

Field names are shared. Duration, resolution, media limits and billing units remain model-specific. Check the catalog and key permissions before switching models. A `null` limit means unconfirmed, not unlimited.

## Common request fields [#common-request-fields]

| Field          | Canonical type | Meaning                                                                                  |
| -------------- | -------------- | ---------------------------------------------------------------------------------------- |
| `model`        | string         | Public model ID                                                                          |
| `prompt`       | string         | Nonempty scene description                                                               |
| `seconds`      | integer        | Output duration within the model's range or enumerated values                            |
| `resolution`   | string         | Model-specific tier; omit if undefined                                                   |
| `aspect_ratio` | string         | Model-specific ratio; omit for models without ratio control                              |
| `images`       | array          | Image URLs or objects containing `url`                                                   |
| `videos`       | array          | Video URLs or objects containing `url` and `seconds`; WAN3 direct requires timed objects |
| `audios`       | array          | Audio URLs or objects containing `url`; MP3 rules depend on the model                    |

Only send media supported by the selected model. Supported image objects may include `role: first_frame / last_frame / reference_image`. WAN3 direct and Seedance Token support these roles. MiniMax and mixed models accept only the default `reference_image` role; unsupported roles are rejected.

The common media contract uses public HTTP(S) URLs without login. No common multipart upload, base64 or asset-review endpoint is promised. Do not copy another service's upload routes onto this site.

This WAN3 direct example uses placeholders. Replace them and confirm the budget before any paid POST:

```json
{
  "model": "wan3.0-video-720p",
  "prompt": "Use the image as the scene and follow the reference camera motion",
  "seconds": 5,
  "aspect_ratio": "16:9",
  "images": [{"url": "https://YOUR_MEDIA_HOST/reference.jpg", "role": "first_frame"}],
  "videos": [{"url": "https://YOUR_MEDIA_HOST/reference.mp4", "seconds": 3}]
}
```

This request bills 8 seconds: 5 output plus 3 reference seconds. Do not apply that formula to per-request or Token models. WAN3 direct permits at most 5 reference videos, each and all together at most 15 seconds, with output plus references at most 30 seconds. Existing deduplication and billing rules remain in effect.

## Legacy compatibility [#legacy-compatibility]

| Legacy field       | Canonical field                           |
| ------------------ | ----------------------------------------- |
| `duration`         | `seconds`                                 |
| `ratio`            | `aspect_ratio`                            |
| `reference_images` | `images`                                  |
| `reference_videos` | `videos`                                  |
| `reference_audios` | `audios`                                  |
| `size`             | `resolution`, when supported by the model |

Integer strings such as `"5"` remain accepted; new clients should send numeric `5`. Avoid sending both aliases. Conflicting values are rejected. WAN3 direct resolution comes from the model ID suffix; `size/resolution` cannot change that tier. The original Seedance multi-image model retains its fixed-720p compatibility behavior.

Seedance Token retains native `content` and explicit `metadata` extensions. Unknown ordinary top-level fields are rejected. Do not override common billing fields through extensions. Its 1–3600 second bound describes gateway validation, not a generation guarantee; actual models and groups may have narrower limits.

## Task responses and downloads [#task-responses-and-downloads]

Save `id` and the `X-Oneapi-Request-Id` response header immediately. Use `id`; do not depend on a legacy `task_id` alias.

```json
{
  "id": "task_EXAMPLE",
  "object": "video",
  "model": "wan3.0-video-720p",
  "status": "queued",
  "progress": 0,
  "created_at": 1780000000
}
```

Poll the same ID every 15 seconds. States are `queued`, `in_progress`, `completed`, `failed` and `expired`. Completed generation can remain `in_progress` while delivery is prepared. Delivery requiring assistance has a separate error code and does not imply an automatic refund.

After completion, download the exact site-signed `metadata.url` without adding a key. Files remain available for about 10 minutes after readiness; one signature lasts at most about 5 minutes. `expires_at` is file expiry. Do not require a top-level `url`. Range and HEAD are supported.

## Error handling [#error-handling]

For HTTP failures read `error.code`, `error.message` and `error.type`:

```json
{
  "error": {
    "code": "video_request_failed",
    "message": "Video request failed. Check task records or contact support before retrying.",
    "type": "api_error"
  }
}
```

Task submission failures temporarily retain sanitized top-level `code/message/data` aliases for older clients. A successful query can return HTTP 200 with `status: failed` and a task `error`.

Invalid site-key authentication returns 401. Internal generation credential failures return 502, so clients should not blindly replace their site key. Public errors exclude service identities, private task identifiers and credentials. Never automatically repeat a creation POST after a timeout, 5xx or missing ID; check task records first. GET requests can be retried with backoff.

See [WAN3](/en/docs/models/), [MiniMax](/en/docs/minimax-models/), [Seedance per request](/en/docs/seedance-flat/) and [mixed models](/en/docs/mixed-models/) for capabilities and billing.