# WAN3 API

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



## Connection [#connection]

| Item     | Value                                |
| -------- | ------------------------------------ |
| Base URL | `https://video.1route.dev`           |
| Auth     | `Authorization: Bearer YOUR_API_KEY` |
| Body     | `application/json`                   |
| Models   | `GET /v1/models`                     |
| Create   | `POST /v1/videos`                    |
| Query    | `GET /v1/videos/{id}`                |

Use `/v1/videos` for new integrations. Do not mix legacy and current paths in one client.

## List models [#list-models]

```bash
curl "https://video.1route.dev/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Use only model IDs returned for the current key.

## Text to video [#text-to-video]

```json
{
  "model": "wan3.0-video-480p",
  "prompt": "A red kite floats above a green field. The camera slowly moves forward.",
  "seconds": "2",
  "aspect_ratio": "16:9"
}
```

## Image to video [#image-to-video]

```json
{
  "model": "wan3.0-image-480p",
  "prompt": "The person in image 1 blinks and turns their head slightly. Keep identity consistent.",
  "seconds": "2",
  "aspect_ratio": "9:16",
  "reference_images": [
    {"url": "https://media.example.com/person.jpg"}
  ]
}
```

First and last frames use `role`:

```json
{
  "model": "wan3.0-video-720p",
  "prompt": "Transition naturally from the first frame to the last frame.",
  "seconds": "5",
  "aspect_ratio": "adaptive",
  "reference_images": [
    {"url": "https://media.example.com/start.jpg", "role": "first_frame"},
    {"url": "https://media.example.com/end.jpg", "role": "last_frame"}
  ]
}
```

Up to 10 images are documented. Roles: `reference_image`, `first_frame`, `last_frame`.

## Image, video and audio references [#image-video-and-audio-references]

```json
{
  "model": "wan3.0-video-480p",
  "prompt": "Keep the subject from image 1, follow motion in video 1 and rhythm in audio 1.",
  "seconds": "10",
  "aspect_ratio": "9:16",
  "reference_images": [{"url": "https://media.example.com/character.jpg"}],
  "reference_videos": [{"url": "https://media.example.com/motion.mp4", "duration": 5}],
  "reference_audios": [{"url": "https://media.example.com/rhythm.mp3"}]
}
```

This is billed as 15 seconds: 10 output + 5 reference. Image-family models reject video references.

## Fields [#fields]

| Field                 | Type            | Meaning                                              |
| --------------------- | --------------- | ---------------------------------------------------- |
| `model`               | required string | WAN3 ID returned by the model list                   |
| `prompt`              | required string | Description; refer to media by order                 |
| `seconds`             | required string | 2–30 whole output seconds                            |
| `aspect_ratio`        | string          | `16:9`, `9:16`, `1:1`, `adaptive`                    |
| `reference_images`    | object\[]       | URL and optional role; up to 10                      |
| `reference_videos`    | object\[]       | URL and explicit whole duration/seconds              |
| `reference_audios`    | object\[]       | Audio URL                                            |
| `size` / `resolution` | string          | Compatibility fields; model suffix controls the tier |

Send `seconds` only; do not send conflicting duration aliases. Media must be directly downloadable. Prefer HTTPS.

Advanced `input.media` types are `first_frame`, `last_frame`, `reference_image`, `reference_audio`, and `reference_video`. Prefer the top-level reference fields for new clients. Do not duplicate one video across both representations.

## Create [#create]

```bash
curl -X POST "https://video.1route.dev/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "wan3.0-image-480p",
    "prompt": "The subject in image 1 looks up naturally.",
    "seconds": "2",
    "reference_images": [{"url": "https://media.example.com/reference.jpg"}]
  }'
```

Persist the full returned `id` and `X-Oneapi-Request-Id`. Never automatically retry creation.

## Poll [#poll]

```bash
curl "https://video.1route.dev/v1/videos/task_EXAMPLE" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Poll about every 15 seconds. Continue for `queued` and `in_progress`; `completed` is success; `failed` and `expired` are terminal.

Read the exact `metadata.url` from a completed response and download immediately. A signed link needs no extra API key. See [Tasks and downloads](/en/docs/tasks/).

## Complete Python client [#complete-python-client]

[Download wan3\_client.py](/examples/wan3_client.py).

It verifies models and prints a request by default. Creation requires both `--create` and `--confirm-cost`. Resume without creating by passing `--task-id task_...`.

```bash
export WAN3_API_KEY="sk-your-key"
python wan3_client.py --model wan3.0-video-480p --seconds 2
python wan3_client.py --model wan3.0-video-480p --seconds 2 \
  --prompt "A red kite above a green field" --create --confirm-cost
python wan3_client.py --task-id task_EXAMPLE
```