# Vidu Q3 API

> Vidu Q3 video with sound, up to 16 seconds and up to 1080p: from a description, from one frame, from the first and last frames or from references.

Developer: ShengShu
Model key in the API: `vidu`

## 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": "vidu",
  "settings": {
    "mode": "t2v",
    "prompt": "Рыбак на рассвете вытаскивает сеть и говорит: «Сегодня улов что надо!»",
    "tier": "turbo",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5
  }
}'

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": "vidu",
    "settings": {
        "mode": "t2v",
        "prompt": "Рыбак на рассвете вытаскивает сеть и говорит: «Сегодня улов что надо!»",
        "tier": "turbo",
        "resolution": "720p",
        "aspect_ratio": "16:9",
        "duration": 5,
    },
}

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": "vidu",
  "settings": {
    "mode": "t2v",
    "prompt": "Рыбак на рассвете вытаскивает сеть и говорит: «Сегодня улов что надо!»",
    "tier": "turbo",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5
  }
};

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 6 ₽. 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": "vidu",
  "settings": {
    "mode": "t2v",
    "prompt": "Рыбак на рассвете вытаскивает сеть и говорит: «Сегодня улов что надо!»",
    "tier": "turbo",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5
  }
}'
```

- 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="t2v"></a>From a description

> A video from text alone, no pictures are sent.

Value of the mode field: `t2v`

Price in this mode from 6 ₽.

### Parameters

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

#### `prompt` (Required)

What happens in the frame, who is in it, how the camera moves, what can be heard. Lines of the characters can be written right in the description, the lips will match.

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

#### `audio` (Optional)

With sound (speech, effects and ambience) or silent. Sound costs nothing extra.

- Type: String
- Allowed values: `on` (With sound), `off` (Silent)
- Default: `"on"`

#### `tier` (Optional)

Speed: Turbo is faster and cheaper, Pro is more accurate with details, motion and faces. The price depends on it.

- Type: String
- Allowed values: `turbo`, `pro`
- Default: `"turbo"`

#### `resolution` (Optional)

Video quality. The price is per second and depends on the quality.

- Type: String
- Allowed values: `540p`, `720p`, `1080p`
- The set depends on `tier`.
- Default: `"720p"`

#### `duration` (Optional)

Length in seconds, 1 to 16. The price is per second.

- Type: Integer
- Minimum: 1
- Maximum: 16
- Default: `5`

#### `aspect_ratio` (Optional)

Frame aspect ratio.

- Type: String
- Allowed values: `16:9`, `9:16`, `4:3`, `3:4`, `1:1`
- Default: `"9:16"`

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

### Input

- A description is needed in every mode.
- The price is per second of the clip and depends on the mode, speed and quality.

### 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 video from a description

```json
{
  "model": "vidu",
  "settings": {
    "mode": "t2v",
    "prompt": "Рыбак на рассвете вытаскивает сеть и говорит: «Сегодня улов что надо!»",
    "tier": "turbo",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5
  }
}
```

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 takes 1 to 10 minutes depending on length and quality.

| 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="i2v"></a>Animate a frame

> The model sets a picture in motion by the description, keeping what is on it. The video takes the aspect ratio of the picture.

Value of the mode field: `i2v`

Price in this mode from 6 ₽.

### Parameters

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

#### `prompt` (Required)

What happens in the frame, who is in it, how the camera moves, what can be heard. Lines of the characters can be written right in the description, the lips will match.

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

#### `audio` (Optional)

With sound (speech, effects and ambience) or silent. Sound costs nothing extra.

- Type: String
- Allowed values: `on` (With sound), `off` (Silent)
- Default: `"on"`

#### `tier` (Optional)

Speed: Turbo is faster and cheaper, Pro is more accurate with details, motion and faces. The price depends on it.

- Type: String
- Allowed values: `turbo`, `pro`
- Default: `"turbo"`

#### `resolution` (Optional)

Video quality. The price is per second and depends on the quality.

- Type: String
- Allowed values: `540p`, `720p`, `1080p`
- The set depends on `tier`.
- Default: `"720p"`

#### `duration` (Optional)

Length in seconds, 1 to 16. The price is per second.

- Type: Integer
- Minimum: 1
- Maximum: 16
- Default: `5`

#### `image_urls` (Required)

One URL of the picture to animate.

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

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

### Input

- A description is needed in every mode.
- The price is per second of the clip and depends on the mode, speed and quality.
- Images are URLs of JPEG, PNG or WebP files up to 50 MB each.
- One side of a picture cannot be more than 4 times longer than the other.

| Field | Accepts | Formats | Files | File size up to |
|---|---|---|---|---|
| `image_urls` | Images | jpeg, jpg, png, webp | 1 | 50 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 photo

```json
{
  "model": "vidu",
  "settings": {
    "mode": "i2v",
    "prompt": "Кот поворачивает голову к камере и громко мяукает",
    "image_urls": [
      "https://example.com/cat.jpg"
    ],
    "duration": 5
  }
}
```

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 takes 1 to 10 minutes depending on length and quality.

| 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="se2v"></a>First and last frame

> Two pictures: where the video starts and where it ends, the model invents the transition. The video takes the aspect ratio of the frames.

Value of the mode field: `se2v`

Price in this mode from 6 ₽.

### Parameters

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

#### `prompt` (Required)

What happens in the frame, who is in it, how the camera moves, what can be heard. Lines of the characters can be written right in the description, the lips will match.

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

#### `audio` (Optional)

With sound (speech, effects and ambience) or silent. Sound costs nothing extra.

- Type: String
- Allowed values: `on` (With sound), `off` (Silent)
- Default: `"on"`

#### `tier` (Optional)

Speed: Turbo is faster and cheaper, Pro is more accurate with details, motion and faces. The price depends on it.

- Type: String
- Allowed values: `turbo`, `pro`
- Default: `"turbo"`

#### `resolution` (Optional)

Video quality. The price is per second and depends on the quality.

- Type: String
- Allowed values: `540p`, `720p`, `1080p`
- The set depends on `tier`.
- Default: `"720p"`

#### `duration` (Optional)

Length in seconds, 1 to 16. The price is per second.

- Type: Integer
- Minimum: 1
- Maximum: 16
- Default: `5`

#### `image_urls` (Required)

Exactly two URLs in order: the first is the starting frame, the second is the ending frame.

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

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

### Input

- A description is needed in every mode.
- The price is per second of the clip and depends on the mode, speed and quality.
- Images are URLs of JPEG, PNG or WebP files up to 50 MB each.
- The aspect ratios of the two frames must be close: they differ by no more than 1.25 times.

| Field | Accepts | Formats | Files | File size up to |
|---|---|---|---|---|
| `image_urls` | Images | jpeg, jpg, png, webp | 2 | 50 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 transition between frames

```json
{
  "model": "vidu",
  "settings": {
    "mode": "se2v",
    "prompt": "Утро плавно сменяется ночью, камера стоит на месте",
    "image_urls": [
      "https://example.com/first.jpg",
      "https://example.com/last.jpg"
    ]
  }
}
```

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 takes 1 to 10 minutes depending on length and quality.

| 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="r2v"></a>From references

> Up to seven pictures: characters, objects, clothes, settings, style. The model builds a scene from them and keeps them consistent through the clip. The length is 3 seconds or more.

Value of the mode field: `r2v`

Price in this mode from 9 ₽.

### Parameters

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

#### `prompt` (Required)

What happens in the frame, who is in it, how the camera moves, what can be heard. Lines of the characters can be written right in the description, the lips will match.

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

#### `audio` (Optional)

With sound (speech, effects and ambience) or silent. Sound costs nothing extra.

- Type: String
- Allowed values: `on` (With sound), `off` (Silent)
- Default: `"on"`

#### `tier` (Optional)

Speed: Turbo is faster and cheaper, Pro is more accurate with details, motion and faces. The price depends on it. Mix gives the best picture, costs more than Pro and has no 540p.

- Type: String
- Allowed values: `turbo`, `pro`, `mix`
- Default: `"turbo"`

#### `resolution` (Optional)

Video quality. The price is per second and depends on the quality.

- Type: String
- Allowed values: `540p`, `720p`, `1080p`
- The set depends on `tier`.
- Exceptions:

  | `tier` | `resolution` |
  |---|---|
  | `mix` | except `540p` |
- Default: `"720p"`

#### `duration` (Optional)

Length in seconds, 3 to 16. The price is per second.

- Type: Integer
- Minimum: 3
- Maximum: 16
- Default: `5`

#### `aspect_ratio` (Optional)

Frame aspect ratio.

- Type: String
- Allowed values: `16:9`, `9:16`, `1:1`
- Default: `"9:16"`

#### `image_urls` (Required)

One to seven URLs of pictures with what must be in the video.

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

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

### Input

- A description is needed in every mode.
- The price is per second of the clip and depends on the mode, speed and quality.
- Images are URLs of JPEG, PNG or WebP files up to 50 MB each.
- One side of a picture cannot be more than 4 times longer than the other.
- Every picture is at least 128 by 128 pixels.

| Field | Accepts | Formats | Files | File size up to |
|---|---|---|---|---|
| `image_urls` | Images | jpeg, jpg, png, webp | 7 | 50 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 and an object from pictures

```json
{
  "model": "vidu",
  "settings": {
    "mode": "r2v",
    "prompt": "Девушка с первой картинки в куртке со второй идёт по ночной набережной",
    "tier": "pro",
    "resolution": "720p",
    "aspect_ratio": "9:16",
    "duration": 6,
    "image_urls": [
      "https://example.com/girl.png",
      "https://example.com/jacket.png"
    ]
  }
}
```

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 takes 1 to 10 minutes depending on length and quality.

| 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

- [Vidu Q3: features and prices](https://api.cyhub.ai/models/vidu-q3)
- 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), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/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)