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: ShengShuModel key in the API: vidu

For AI assistants:Download .md All documentation .md Open as text

Connect in three steps

Get a keyCreate a key in the dashboard after you confirm your email. One key opens every model.
Check the pricePOST /v1/price shows the cost of a run in advance, without charging you.
Run a task and collect the resultPOST /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.

cURLPythonNode.js

cURL

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"])

Node.js

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

Price before the run

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

Mode	Price
From a description	from 6 ₽
Turbo (faster, cheaper) tier = turbo	from 6 ₽
Pro (more accurate) tier = pro	from 7 ₽
Animate a frame	from 6 ₽
Turbo (faster, cheaper) tier = turbo	from 6 ₽
Pro (more accurate) tier = pro	from 7 ₽
First and last frame	from 6 ₽
Turbo (faster, cheaper) tier = turbo	from 6 ₽
Pro (more accurate) tier = pro	from 7 ₽
From references	from 9 ₽
Turbo (faster, cheaper) tier = turbo	from 9 ₽
Pro (more accurate) tier = pro	from 16 ₽
Mix (best picture) tier = mix	from 52 ₽

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

cURL

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

Modes

Each mode has its own parameters and examples. The mode is set by the mode field.

From a description mode = t2v
Animate a frame mode = i2v
First and last frame mode = se2v
From references mode = r2v

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.

promptRequired: 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: StringMinimum characters: 1Maximum characters: 5000
audioOptional: With sound (speech, effects and ambience) or silent. Sound costs nothing extra.
Type: StringAllowed values: onoffDefault: "on"
tierOptional: Speed: Turbo is faster and cheaper, Pro is more accurate with details, motion and faces. The price depends on it.
Type: StringAllowed values: turboproDefault: "turbo"
resolutionOptional: Video quality. The price is per second and depends on the quality.
Type: StringAllowed values: 540p720p1080pThe set depends on tier.Default: "720p"
durationOptional: Length in seconds, 1 to 16. The price is per second.
Type: IntegerMinimum: 1Maximum: 16Default: 5
aspect_ratioOptional: Frame aspect ratio.
Type: StringAllowed values: 16:99:164:33:41:1Default: "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

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

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.

promptRequired: 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: StringMinimum characters: 1Maximum characters: 5000
audioOptional: With sound (speech, effects and ambience) or silent. Sound costs nothing extra.
Type: StringAllowed values: onoffDefault: "on"
tierOptional: Speed: Turbo is faster and cheaper, Pro is more accurate with details, motion and faces. The price depends on it.
Type: StringAllowed values: turboproDefault: "turbo"
resolutionOptional: Video quality. The price is per second and depends on the quality.
Type: StringAllowed values: 540p720p1080pThe set depends on tier.Default: "720p"
durationOptional: Length in seconds, 1 to 16. The price is per second.
Type: IntegerMinimum: 1Maximum: 16Default: 5
image_urlsRequired: 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

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

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

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.

promptRequired: 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: StringMinimum characters: 1Maximum characters: 5000
audioOptional: With sound (speech, effects and ambience) or silent. Sound costs nothing extra.
Type: StringAllowed values: onoffDefault: "on"
tierOptional: Speed: Turbo is faster and cheaper, Pro is more accurate with details, motion and faces. The price depends on it.
Type: StringAllowed values: turboproDefault: "turbo"
resolutionOptional: Video quality. The price is per second and depends on the quality.
Type: StringAllowed values: 540p720p1080pThe set depends on tier.Default: "720p"
durationOptional: Length in seconds, 1 to 16. The price is per second.
Type: IntegerMinimum: 1Maximum: 16Default: 5
image_urlsRequired: 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

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

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

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.

promptRequired: 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: StringMinimum characters: 1Maximum characters: 5000
audioOptional: With sound (speech, effects and ambience) or silent. Sound costs nothing extra.
Type: StringAllowed values: onoffDefault: "on"
tierOptional: 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: StringAllowed values: turbopromixDefault: "turbo"
resolutionOptional: Video quality. The price is per second and depends on the quality.
Type: StringAllowed values: 540p720p1080pThe set depends on tier.
Exceptions
tier resolution
mix except 540p
Default: "720p"
durationOptional: Length in seconds, 3 to 16. The price is per second.
Type: IntegerMinimum: 3Maximum: 16Default: 5
aspect_ratioOptional: Frame aspect ratio.
Type: StringAllowed values: 16:99:161:1Default: "9:16"
image_urlsRequired: One to seven URLs of pictures with what must be in the video.
Type: List (String, uri)Maximum items: 7

`tier`	`resolution`
`mix`	except `540p`

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

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

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

Try Vidu Q3 through the API

One key opens every CyHUB model. Payment in rubles, and you see the price before the run.

Get an API key

Vidu Q3 API

Connect in three steps

Ready-to-use code

Price before the run

Modes

From a description

Parameters

Input

Request example

Output

Animate a frame

Parameters

Input

Request example

Output

First and last frame

Parameters

Input

Request example

Output

From references

Parameters

Input

Request example

Output

See also

Try Vidu Q3 through the API