# Wan 3.0 API

> Wan 3.0 video from the first and last frames, from references and in the Omni mode, where pictures, video and sound go together. 2 to 30 seconds, up to 1080p.

Developer: Alibaba
Model key in the API: `wan`

## Connect in three steps

1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model.
2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you.
3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files.

## Ready-to-use code

Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded.

```bash
curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "wan",
  "settings": {
    "mode": "frames",
    "prompt": "Медведь медленно поворачивает голову и улыбается, листья падают",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "quality": "720p",
    "duration": "5s",
    "model": "3_0"
  }
}'

curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import time

import requests

API = "https://api.cyhub.ai/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

body = {
    "model": "wan",
    "settings": {
        "mode": "frames",
        "prompt": "Медведь медленно поворачивает голову и улыбается, листья падают",
        "image_urls": [
            "https://example.com/first-frame.jpg",
        ],
        "quality": "720p",
        "duration": "5s",
        "model": "3_0",
    },
}

response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60)
response.raise_for_status()
task = response.json()
while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json()
print(task["status"], task["result"])
```

```javascript
const API = "https://api.cyhub.ai/v1";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const body = {
  "model": "wan",
  "settings": {
    "mode": "frames",
    "prompt": "Медведь медленно поворачивает голову и улыбается, листья падают",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "quality": "720p",
    "duration": "5s",
    "model": "3_0"
  }
};

async function main() {
  let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) });
  if (!response.ok) throw new Error(await response.text());
  let task = await response.json();
  while (task.status === "queued" || task.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS });
    task = await response.json();
  }
  console.log(task.status, task.result);
}

main();
```

[Get a key](https://cyhub.ai/cabinet/keys)

## Price before the run

Prices as of 15.10.2026: from 16 ₽. POST /v1/price shows the exact price of your settings.

Send the same settings to POST /v1/price: the response shows the price of the run without charging you.

```bash
curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "wan",
  "settings": {
    "mode": "frames",
    "prompt": "Медведь медленно поворачивает голову и улыбается, листья падают",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "quality": "720p",
    "duration": "5s",
    "model": "3_0"
  }
}'
```

- amount_minor: the price of the run in minor units (kopecks for rubles)
- currency: the wallet currency
- available_minor: how much your balance has for new tasks right now

## <a id="frames"></a>From frames

> The first frame, or the first and the last one: the model animates them by the prompt. Wan 3.0 needs a frame, the other versions also work without one.

Value of the mode field: `frames`

Price in this mode from 16 ₽.

### Parameters

Model parameters go inside settings. Omitted optional fields take their default values.

#### `prompt` (Required)

What happens in the video: scene, motion, camera, style. Up to 5,000 characters, up to 20,000 for Wan 3.0.

- Type: String
- Minimum characters: 1
- Maximum characters: 20000

#### `image_urls` (Optional)

One URL: the first frame. Two URLs: the first and the last frames.

- Type: List (String, uri)
- Maximum items: 2

#### `model` (Optional)

Wan version. 3.0, the newest one, has no own sound and no splitting into scenes.

- Type: String
- Allowed values: `3_0` (Wan 3.0)
- Default: `"3_0"`

#### `quality` (Optional)

Video resolution; the set depends on the version. The price per second depends on it.

- Type: String
- Allowed values: `480p`, `720p`, `1080p`
- Default: `"720p"`

#### `aspect_ratio` (Optional)

Frame shape. Wan 2.5 at 480p offers only 16:9, 9:16 and 1:1.

- Type: String
- Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
- The set depends on `quality`.
- Default: `"16:9"`

#### `duration` (Optional)

Video length: 5 or 10 seconds for Wan 2.5, 2 to 15 for 2.6 and 2.7, 2 to 30 for 3.0. The price is per second.

- Type: String
- Allowed values: `2s` (2 sec), `3s` (3 sec), `4s` (4 sec), `5s` (5 sec), `6s` (6 sec), `7s` (7 sec), `8s` (8 sec), `9s` (9 sec), `10s` (10 sec), `11s` (11 sec), `12s` (12 sec), `13s` (13 sec), `14s` (14 sec), `15s` (15 sec), `16s` (16 sec), `17s` (17 sec), `18s` (18 sec), `19s` (19 sec), `20s` (20 sec), `21s` (21 sec), `22s` (22 sec), `23s` (23 sec), `24s` (24 sec), `25s` (25 sec), `26s` (26 sec), `27s` (27 sec), `28s` (28 sec), `29s` (29 sec), `30s` (30 sec)
- Default: `"5s"`

#### `multi_shots` (Optional)

Split the video into several scenes. Wan 2.6 and 2.7 only.

- Type: Boolean
- Default: `false`

#### `audio` (Optional)

Your own sound for the video, such as a voice or music: one URL. Available in Wan 2.6 and 2.7. Sound longer than the video is cut to its length.

- Type: List (String, uri)
- Maximum items: 1

Parameters not listed here are not accepted: the response is 422 unknown_setting.

### Input

- Frames are URLs of JPEG, PNG or WebP files up to 10 MB each.
- Sound is a URL of an MP3 or WAV file up to 10 MB.

| Field | Accepts | Formats | Files | File size up to |
|---|---|---|---|---|
| `image_urls` | Images | jpeg, jpg, png, webp | 2 | 10 MB |
| `audio` | Audio | mp3, wav | 1 | 10 MB |

[How to send files](https://api.cyhub.ai/docs/files.md?lang=en)

### Request example

Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.

Animate a frame

```json
{
  "model": "wan",
  "settings": {
    "mode": "frames",
    "prompt": "Медведь медленно поворачивает голову и улыбается, листья падают",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "quality": "720p",
    "duration": "5s"
  }
}
```

The price is calculated when the task is accepted, currency `RUB`.

[Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en)

### Output

- One MP4 video.
- Generation usually takes 5 to 10 minutes.

| Kind | Formats | How many | Note |
|---|---|---|---|
| `video` | mp4 | 1 |  |

A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Caption of the result: the model and its settings",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result)

## <a id="reference"></a>From references

> Characters, objects and places from your pictures and videos in a new video. Versions 2.7 and 3.0.

Value of the mode field: `reference`

Price in this mode from 16 ₽.

### Parameters

Model parameters go inside settings. Omitted optional fields take their default values.

#### `prompt` (Required)

What happens in the video. Refer to the attachments by the labels @Image1, @Video1, each one must be mentioned. Up to 5,000 characters, up to 20,000 for Wan 3.0.

- Type: String
- Minimum characters: 1
- Maximum characters: 20000

#### `ref_image_urls` (Optional)

Pictures with characters, objects or a place, @Image1, @Image2 in the prompt in the order of the URLs. Up to 5 pictures and videos together, at least one of them is required.

- Type: List (String, uri)
- Maximum items: 5

#### `ref_video_urls` (Optional)

Videos with a character, @Video1, @Video2 in the prompt. Each is 1 to 5 seconds, their seconds are included in the price. With a video, Wan 2.7 makes a video of 10 seconds at most.

- Type: List (String, uri)
- Maximum items: 5

#### `first_frame_url` (Optional)

The first frame of the video, optional. With it the video takes the shape of the frame, and aspect_ratio has no effect.

- Type: List (String, uri)
- Maximum items: 1

#### `model` (Optional)

Wan version: 2.7 or 3.0.

- Type: String
- Allowed values: `3_0` (Wan 3.0)
- Default: `"3_0"`

#### `quality` (Optional)

Video resolution; the set depends on the version. The price per second depends on it.

- Type: String
- Allowed values: `480p`, `720p`, `1080p`
- Default: `"720p"`

#### `aspect_ratio` (Optional)

Frame shape.

- Type: String
- Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
- The set depends on `quality`.
- Default: `"16:9"`

#### `duration` (Optional)

Video length: 2 to 15 seconds for Wan 2.7, up to 10 with a video among the attachments; 2 to 30 for 3.0. The price is per second.

- Type: String
- Allowed values: `2s` (2 sec), `3s` (3 sec), `4s` (4 sec), `5s` (5 sec), `6s` (6 sec), `7s` (7 sec), `8s` (8 sec), `9s` (9 sec), `10s` (10 sec), `11s` (11 sec), `12s` (12 sec), `13s` (13 sec), `14s` (14 sec), `15s` (15 sec), `16s` (16 sec), `17s` (17 sec), `18s` (18 sec), `19s` (19 sec), `20s` (20 sec), `21s` (21 sec), `22s` (22 sec), `23s` (23 sec), `24s` (24 sec), `25s` (25 sec), `26s` (26 sec), `27s` (27 sec), `28s` (28 sec), `29s` (29 sec), `30s` (30 sec)
- Default: `"5s"`

#### `multi_shots` (Optional)

Split the video into several scenes. Wan 2.7 only.

- Type: Boolean
- Default: `false`

Parameters not listed here are not accepted: the response is 422 unknown_setting.

### Input

- Every attachment must be mentioned in the prompt by its label: @Image1, @Image2, @Video1 and so on. The number is the position of the URL in the field of its type. Write it exactly like this: capital letter, no space.
- Pictures are URLs of JPEG, PNG or WebP files up to 10 MB each, videos are URLs of MP4 or MOV files up to 100 MB.
- A video goes to the model whole, without trimming, and its seconds are included in the price.

| Field | Accepts | Formats | Files | File size up to |
|---|---|---|---|---|
| `ref_image_urls` | Images | jpeg, jpg, png, webp | 5 | 10 MB |
| `ref_video_urls` | Video | mp4, mov | 5 | 100 MB |
| `first_frame_url` | Images | jpeg, jpg, png, webp | 1 | 10 MB |

[How to send files](https://api.cyhub.ai/docs/files.md?lang=en)

### Request example

Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.

A character from a picture

```json
{
  "model": "wan",
  "settings": {
    "mode": "reference",
    "prompt": "@Image1 идёт по ночному городу под дождём, камера следует за ним",
    "ref_image_urls": [
      "https://example.com/hero.png"
    ],
    "aspect_ratio": "9:16",
    "duration": "5s"
  }
}
```

The price is calculated when the task is accepted, currency `RUB`.

[Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en)

### Output

- One MP4 video.
- Generation usually takes 5 to 10 minutes.

| Kind | Formats | How many | Note |
|---|---|---|---|
| `video` | mp4 | 1 |  |

A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Caption of the result: the model and its settings",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result)

## <a id="omni"></a>Omni

> Pictures, video and sound together, each attachment with its own label in the prompt. Wan 3.0 only.

Value of the mode field: `omni`

Price in this mode from 24 ₽, with a 1 s file.

### Parameters

Model parameters go inside settings. Omitted optional fields take their default values.

#### `prompt` (Required)

What happens in the video. Refer to the attachments by the labels @Image1, @Video1, @Audio1, each one must be mentioned. Up to 20,000 characters.

- Type: String
- Minimum characters: 1
- Maximum characters: 20000

#### `ref_image_urls` (Optional)

Pictures, @Image1, @Image2 in the prompt in the order of the URLs, up to 10.

- Type: List (String, uri)
- Maximum items: 10

#### `ref_video_urls` (Optional)

Videos, @Video1, @Video2 in the prompt. Each is 1 to 15 seconds, 15 at most together. Their seconds are included in the price.

- Type: List (String, uri)
- Maximum items: 5

#### `ref_audio_urls` (Optional)

Sound, such as a voice for a line, @Audio1, @Audio2 in the prompt. Each is 1 to 15 seconds, 15 at most together.

- Type: List (String, uri)
- Maximum items: 5

#### `model` (Optional)

Wan version: only 3.0 has this mode.

- Type: String
- Allowed values: `3_0` (Wan 3.0)
- Default: `"3_0"`

#### `quality` (Optional)

Video resolution; the set depends on the version. The price per second depends on it.

- Type: String
- Allowed values: `480p`, `720p`, `1080p`
- Default: `"720p"`

#### `aspect_ratio` (Optional)

Frame shape.

- Type: String
- Allowed values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`
- The set depends on `quality`.
- Default: `"16:9"`

#### `duration` (Optional)

Video length from 2 to 30 seconds. The price is per second.

- Type: String
- Allowed values: `2s` (2 sec), `3s` (3 sec), `4s` (4 sec), `5s` (5 sec), `6s` (6 sec), `7s` (7 sec), `8s` (8 sec), `9s` (9 sec), `10s` (10 sec), `11s` (11 sec), `12s` (12 sec), `13s` (13 sec), `14s` (14 sec), `15s` (15 sec), `16s` (16 sec), `17s` (17 sec), `18s` (18 sec), `19s` (19 sec), `20s` (20 sec), `21s` (21 sec), `22s` (22 sec), `23s` (23 sec), `24s` (24 sec), `25s` (25 sec), `26s` (26 sec), `27s` (27 sec), `28s` (28 sec), `29s` (29 sec), `30s` (30 sec)
- Default: `"5s"`

Parameters not listed here are not accepted: the response is 422 unknown_setting.

### Input

- Every attachment must be mentioned in the prompt by its label: @Image1, @Image2, @Video1 and so on. The number is the position of the URL in the field of its type. Write it exactly like this: capital letter, no space.
- At least one attachment is needed.
- Pictures are URLs of JPEG, PNG or WebP files up to 10 MB each, videos are URLs of MP4 or MOV files up to 100 MB, sound is URLs of MP3 or WAV files up to 10 MB.
- A video goes to the model whole, without trimming, and its seconds are included in the price.

| Field | Accepts | Formats | Files | File size up to |
|---|---|---|---|---|
| `ref_image_urls` | Images | jpeg, jpg, png, webp | 10 | 10 MB |
| `ref_video_urls` | Video | mp4, mov | 5 | 100 MB |
| `ref_audio_urls` | Audio | mp3, wav | 5 | 10 MB |

[How to send files](https://api.cyhub.ai/docs/files.md?lang=en)

### Request example

Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price.

Two characters talking

```json
{
  "model": "wan",
  "settings": {
    "mode": "omni",
    "prompt": "@Image1 приходит к @Image2 и говорит ему @Audio1. Фон как в @Video1, звук из видео не брать",
    "ref_image_urls": [
      "https://example.com/fox.png",
      "https://example.com/bear.png"
    ],
    "ref_video_urls": [
      "https://example.com/forest.mp4"
    ],
    "ref_audio_urls": [
      "https://example.com/line.mp3"
    ],
    "quality": "480p",
    "duration": "5s"
  }
}
```

The price is calculated when the task is accepted, currency `RUB`.

[Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en)

### Output

- One MP4 video.
- Generation usually takes 5 to 10 minutes.

| Kind | Formats | How many | Note |
|---|---|---|---|
| `video` | mp4 | 1 |  |

A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "succeeded",
  "finished_at": "2026-10-01T12:03:41+00:00",
  "result": {
    "caption": "Caption of the result: the model and its settings",
    "texts": [],
    "files_expire_at": "2026-10-08T12:03:41+00:00",
    "files_expired": false,
    "artifacts": [
      {
        "index": 0,
        "kind": "video",
        "filename": "video.mp4",
        "size": 12582912,
        "caption": "",
        "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0"
      }
    ]
  }
}
```

[How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result)

## See also

- [Wan 3.0: features and prices](https://api.cyhub.ai/models/wan-3)
- Other versions: [Wan 2.7 API](https://api.cyhub.ai/en/models/wan-2-7/api.md), [Wan 2.6 API](https://api.cyhub.ai/en/models/wan-2-6/api.md), [Wan 2.5 API](https://api.cyhub.ai/en/models/wan-2-5/api.md)
- Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md), [Gemini Omni API](https://api.cyhub.ai/en/models/gemini-omni/api.md)
- [API documentation](https://api.cyhub.ai/docs.md?lang=en)
- [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en)