Vidu Q Video Models

Vidu Q2

Reference to Video

Q2 Create Task

POST/ent/v2/reference2video

Q2 Query Creations

GET/ent/v2/tasks/{id}/creations

Q2 Pro Create Task

POST/ent/v2/reference2video

Reference to Video (Subject Invocation)

Subject creation method: https://platform.vidu.cn/docs/subjects

Q2 Pro Query Creations

GET/ent/v2/tasks/{id}/creations

Subjects-Reference to Video

Headers

Authorizationstring*

Replace `{your api key}` with your API key

Example:Token \{your api key}\

Body parameters

modelstring*

Model name
Accepted values: `viduq2`

Headers

Authorizationstring*

Replace `{your api key}` with your API key

Example:Token \{your api key}\

Path parameters

idstring*

Task ID, returned by the Create Task API upon successful creation

Response

Headers

Authorizationstring*

Replace {your api key} with your token

Example:Token {your api key}

Body parameters

modelstring*

Model name. Accepted value: viduq2-pro

viduq2-pro: Supports video reference, video editing, and video replacement.

imagesarray

Headers

Authorizationstring*

Replace {your api key} with your token

Example:Token {your api key}

Path parameters

idstring*

No description

Body parameters

idstring*

Task ID returned after the task creation request succeeds

Response

viduq2: Good dynamic effect and rich generated details

auto_subjectsboolean

Whether to use the intelligent subject library capability. Default: false. Accepted values: true / false

true: Use the intelligent subject library capability.
false: Do not use the intelligent subject library capability.

subjectsstring*

When using the q3, q2, q1, and 2.0 models, only image subjects and text subjects can be used

Up to 7 image or text subjects

namestring*

User-specified subject name. During generation, it can be referenced via [@name], for

Example:[@Image1]normal

imagesarray

Temporary subject images, up to 3 imagesNote 1: Accepts Base64-encoded images or image URLs (ensure they are accessible)Note 2: Supported image formats: png, jpeg, jpg, webpNote 3: Image dimensions must not be less than 128*128 pixels, and the aspect ratio must be less than 1:4 or 4:1Note 4: The HTTP POST body must not exceed 20MB, and the encoding must include an appropriate content type string. For normal

promptstring*

Text prompt: a textual description for video generation.
Note 1: Maximum length is 5000 characters
Note 2: Use [@subjects_name] to represent subject content. For normal

Example:@1 and @2 are eating hot pot together, and the narration says everyone loves hot pot.

audioboolean

Whether to use direct audio-video generation. Default: false. Accepted values: true / false

true: Use direct audio-video generation.
false: Do not use direct audio-video generation.

durationinteger

Video duration. Default value depends on the model:
`viduq2`: default 5 seconds, available: 1 - 10

seedinteger

Random seed. When not provided or set to 0, a random number is used; manually set values will be used as the seed

aspect_ratiostring

Aspect ratio. The q2 and q3 models support any aspect ratio or auto
Defaults to `16:9`. Accepted values: 1:1, 9:16, 16:9, 3:4, 4:3
auto: automatically recommended based on the input image or video

resolutionstring

Resolution. Default value depends on the model and video duration:
`viduq2` (1-10s): default 720p, available: 540p, 720p, 1080p

payloadstring

Transparent transmission parameters. No processing, only data transmission
Note: Maximum length is 1048576 characters

off_peakboolean

Off-peak mode. Default: false. Accepted values:

true: Generate videos in off-peak mode;
false: Generate videos immediately;
Note 1: Off-peak mode consumes lower credits. Please refer to Pricing for details
Note 2: Tasks submitted in off-peak mode will be generated within 48 hours. Tasks that fail to complete will be automatically cancelled and their credits refunded
Note 3: You can also manually cancel off-peak tasks
Note 4: The q2, q1, and 2.0 series models support off-peak tasks when audio is false

callback_urlstring

Callback protocol
When creating a task, you need to actively set the callback_url. The request method is POST. When the status of a video generation task changes, Vidu will send a callback request containing the latest task status to this address. The callback request content structure is consistent with the response body of the Get Generation Task API
The callback-returned "status" includes the following states:

processing: task is being processed
success: task completed (if sending fails, retries the callback three times)
failed: task failed (if sending fails, retries the callback three times)
Vidu uses a callback signature algorithm for authentication. For details, see Callback Signature

Image reference supports multiple images. The model uses the subjects in the images provided in this parameter as references to generate a video with consistent subjects. The supported number of images varies by model version. Details are as follows:normalNote 1: When using the viduq2-pro model, if no video is uploaded, 1 to 7 images are supported; if a video is uploaded, 1 to 4 images are supported.bulletnormalNote 2: Images can be provided as Base64-encoded data or image URLs (ensure that the URLs are accessible).bulletnormalNote 3: Supported image formats: PNG, JPEG, JPG, and WebP.bulletnormalNote 4: Image dimensions must be at least 128 x 128 pixels, and the aspect ratio must be less than 1:4 or 4:1.bulletnormalNote 5: The POST body of the HTTP request must not exceed 20MB, and the encoding must include an appropriate content type string. For base64,{base64_encode}bulletnormal

Example:data:image/png

videosarray

Video reference supports uploading 1 to 2 videos. The model uses the videos provided in this parameter as references to generate a video with consistent subjects.normalNote 1: This parameter is only supported by the viduq2-pro model.bulletnormalNote 2: When using the video reference feature, supports uploading at most 1 video of 8 seconds or 2 videos of 5 seconds.bulletnormalNote 3: Supported video formats: MP4, AVI, and MOV.bulletnormalNote 4: Video resolution cannot be less than 128 x 128 pixels, the aspect ratio must be less than 1:4 or 4:1, and the size must not exceed 100MB.bulletnormalNote 5: The byte length after Base64 decoding must be less than 20MB, and the encoding must include an appropriate content type string. For base64,{base64_encode}bulletnormal

Example:data:video/mp4

promptstring*

Text prompt for video generation.
Note: The maximum length is 5000 characters.

durationinteger

Video duration parameter. Default values depend on the model:
viduq2-pro: Default is 5 seconds, available options: 1-10

seedinteger

Random seed. If omitted or set to 0, a random number is used. If manually set, the specified seed is used.

aspect_ratiostring

Defaults to 16:9. Accepted values: 1:1, 9:16, 16:9, 3:4, 4:3
auto: Automatically recommends an aspect ratio based on the input image or video.

resolutionstring

Resolution parameter. Default values depend on the model and video duration:
viduq2-pro (1-10 seconds): Default is 720p, available options: 540p, 720p, 1080p

payloadstring

Transparent transmission parameter. No processing is performed; data is only transmitted.
Note: The maximum length is 1048576 characters.

off_peakboolean

Off-peak mode. Defaults to false. Accepted values: true, false

true: Generate the video during off-peak hours.
false: Generate the video immediately.
Note 1: Off-peak mode consumes fewer credits. For details, see product pricing.
Note 2: Tasks submitted in off-peak mode will be generated within 48 hours. Tasks that are not completed will be automatically cancelled, and the credits for the task will be refunded.
Note 3: You can also manually cancel off-peak tasks.
Note 4: The q2, q1, and 2.0 series models support off-peak tasks when audio is false.

callback_urlstring

Callback protocol.
When creating a task, you need to actively set the callback_url with a POST request. When the video generation task changes its status, Vidu will send a callback request to this URL, containing the latest status of the task. The structure of the callback request content will be the same as the return body of the Query Task API.
The status in the callback response includes the following states:

processing: Task is being processed.
success: Task is completed. If sending fails, the callback will be retried three times.
failed: Task failed. If sending fails, the callback will be retried three times.
Vidu uses a callback signature algorithm for authentication. For details, see Callback Signature.

Example:data:image/png;base64,{base64_encode}

videosarray

Temporary subject videos, up to one 5-second video
Note 1: Only the reference-to-video viduq2-pro model supports video subjects
Note 2: Supports uploading at most one 5-second video
Note 3: Supported video formats: mp4, avi, mov
Note 4: Video dimensions must not be less than 128*128 pixels, and the aspect ratio must be less than 1:4 or 4:1
Note 5: The byte length after base64 decoding must be less than 20MB, and the encoding must include an appropriate content type string. For normal

Example:data:video/mp4;base64,{base64_encode}

voice_idstring

Voice ID, used to determine the voice timbre in the video. If empty, the system will automatically recommend one. For optional enumerated values, refer to the Voice List
Alternatively, you can use the Voice Cloning API to clone any voice, and the voice_id is interchangeable

server_idstring

The subject ID obtained from the Create Subject API
Note: If server_id is not provided, the subject is treated as temporary and will not be saved by the system

200OKapplication/json

Response fields

idstring

Task ID

statestring

Processing state
Accepted values:
`created` created successfully
`queueing` task in queue
`processing` processing
`success` generation successful
`failed` task failed

err_codestring

Error code, see the error code table for details

creditsinteger

The number of credits consumed by this task (unit: credits)

payloadstring

The payload (pass-through) parameter passed in for this task call

bgmboolean

Whether bgm is used for this task call

off_peakboolean

Whether off-peak mode is used for this task call

creationsarray

Generation results

idstring

Generation ID, used to identify different creations

urlstring

Creation URL, valid for 24 hours

cover_urlstring

Creation cover, valid for 24 hours

watermarked_urlstring

200OKapplication/json

Response fields

task_idstring

Task ID

statestring

It will be returned to a specific processing state:

`created` created task successfully
`queueing` task in queue
`processing` processing
`success` generation successful
`failed` task failed

200OKapplication/json

Response fields

task_idstring

Task ID generated by Vidu

statestring

Processing status
Accepted values:

created: Task created successfully
queueing: Task is in the queue
processing: Task is being processed
: Task completed successfully

200OKapplication/json

Response fields

idstring

Task ID

statestring

Processing status
Available values:

created: Task created successfully
queueing: Task is in the queue
processing: Task is being processed
: Task completed successfully

Watermarked creation URL, valid for 24 hours

The model parameter used for this call

promptstring

The text prompt used for this call

imagesstring

The images used for this call

durationinteger

The video duration parameter used for this call

seedinteger

The random seed parameter used for this call

aspect_ratiostring

The aspect ratio parameter used for this call

resolutionstring

The resolution parameter used for this call

bgmboolean

The background music parameter used for this call

movement_amplitudestring

The camera movement amplitude parameter used for this call

payloadstring

The payload parameter used for this call

off_peakboolean

Whether off-peak mode is used for this call

creditsinteger

The credits used for this call

watermarkboolean

Whether a watermark is used for this call

created_atstring

Task creation time

failed: Task failed

modelstring

The model name used for this call

promptstring

The prompt parameter used for this call

imagesarray

The image parameters used for this call

durationinteger

The video duration parameter used for this call

seedinteger

The random seed parameter used for this call

aspect_ratiostring

The aspect ratio parameter used for this call

resolutionstring

The resolution parameter used for this call

payloadstring

The transparent transmission parameter used for this call

off_peakboolean

Whether off-peak mode was used for this call

creditsinteger

The number of credits used for this call

created_atstring

Task creation time

failed: Task failed

err_codestring

Error code. For details, see the error code table.

creditsinteger

The number of credits consumed by this task

payloadstring

The transparent transmission parameter provided for this task

bgmboolean

Whether background music was used for this task

off_peakboolean

Whether off-peak mode was used for this task

creationsarray

Generated results

idstring

Generated result ID, used to identify different generated results

urlstring

Generated result URL, valid for 24 hours

cover_urlstring

Generated result cover URL, valid for 24 hours

watermarked_urlstring

Watermarked generated result URL, valid for 24 hours

Request example

curl --request POST \
  --url 'https://api.vidu.com/ent/v2/reference2video' \
  --header 'Authorization: Token {your api key}\' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "viduq2",
  "auto_subjects": true,
  "subjects": {
    "name": "[@Image1]normal",
    "images": "data:image/png;base64,{base64_encode}",
    "videos": "data:video/mp4;base64,{base64_encode}",
    "voice_id": "string",
    "server_id": "string"
  },
  "prompt": "@1 and @2 are eating hot pot together, and the narration says everyone loves hot pot.",
  "audio": true,
  "duration": 8,
  "seed": 0,
  "aspect_ratio": "3:4",
  "resolution": "1080p",
  "payload": "string",
  "off_peak": true,
  "callback_url": "string"
}'

200

Response example

{
  "task_id": "your_task_id_here",
  "state": "created",
  "model": "viduq2",
  "images": [""],
  "prompt": "[@1] and [@2] are eating hot pot together with [@3]",
  "duration": 5,
  "seed": random_number,
  "aspect_ratio": "3:4",
  "resolution": "720p",
  "audio": true,
  "payload":"",
  "off_peak": false,
  "credits":credits_number,
  "created_at": "2025-01-01T15:41:31.968916Z"
}

{
  "task_id": "your_task_id_here",
  "state": "created",
  "model": "viduq2",
  "images": ["https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-1.png","https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-2.png","https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-3.png"],
  "prompt": "Santa Claus and the bear hug by the lakeside.",
  "duration": 5,
  "seed": random_number,
  "aspect_ratio": "3:4",
  "resolution": "540p",
  "movement_amplitude": "auto",
  "payload":"",
  "off_peak": false,
  "credits":credits_number,
  "created_at": "2025-01-01T15:41:31.968916Z"
}

Request example

curl --request GET \
  --url 'https://api.vidu.com/ent/v2/tasks/{your_id}/creations' \
  --header 'Authorization: Token {your api key}\'

200

Response example

{
  "id":"your_task_id",
  "state": "success",
  "err_code": "",
  "credits": 4,
  "payload": "",
  "creations": [
    {
      "id": "your_creations_id",
      "url": "your_generated_results_url",
      "cover_url": "your_generated_results_cover_url",
      "watermarked_url": "your_generated_results_watermarked_url"
    }
  ]
}

Request example

curl --request POST \
  --url 'https://api.vidu.cn/ent/v2/reference2video' \
  --header 'Authorization: Token {your api key}' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "viduq2-pro",
  "images": "data:image/png",
  "videos": "data:video/mp4",
  "prompt": "Santa Claus and the bear hug by the lakeside.",
  "duration": 5,
  "seed": 0,
  "aspect_ratio": "3:4",
  "resolution": "1080p",
  "payload": "string",
  "off_peak": true,
  "callback_url": "string"
}'

200

Response example

{
  "task_id": "your_task_id_here",
  "state": "created",
  "model": "viduq2-pro",
  "images": ["https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-1.png","https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-2.png","https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-3.png"],
  "prompt": "Santa Claus and the bear hug by the lakeside.",
  "duration": 5,
  "seed": random_number,
  "aspect_ratio": "3:4",
  "resolution": "540p",
  "payload":"",
  "credits":credits_number,
  "created_at": "2025-01-01T15:41:31.968916Z"
}

{
  "task_id": "your_task_id_here",
  "state": "created",
  "model": "viduq2-pro",
  "images": [""],
  "prompt": "[@1] and [@2] are eating hot pot together at [@3]",
  "duration": 5,
  "seed": random_number,
  "aspect_ratio": "3:4",
  "resolution": "720p",
  "audio": true,
  "payload":"",
  "off_peak": false,
  "credits":credits_number,
  "created_at": "2025-01-01T15:41:31.968916Z"
}

Request example

curl --request GET \
  --url 'https://api.vidu.cn/ent/v2/tasks/{your_id}/creations' \
  --header 'Authorization: Token {your api key}' \
  --header 'Content-Type: application/json'

200

Response example

{
  "id":"your_task_id",
  "state": "success",
  "err_code": "",
  "credits": 4,
  "payload": "",
  "creations": [
    {
      "id": "your_creations_id",
      "url": "your_generated_results_url",
      "cover_url": "your_generated_results_cover_url",
      "watermarked_url": "your_generated_results_watermarked_url"
    }
  ]
}

Features

Get started

About Us

Features

Get started

About Us

Vidu Q2

Reference to Video

Q2 Create Task

Q2 Query Creations

Q2 Pro Create Task

Reference to Video (Subject Invocation)

Q2 Pro Query Creations

Subjects-Reference to Video

Headers

Body parameters

Headers

Path parameters

Response

Headers

Body parameters

Headers

Path parameters

Body parameters

Response

Response

Response

Search documentation

Features

Get started

About Us

Search documentation

Features

Get started

About Us

Vidu Q2

Reference to Video

Q2 Create Task

Q2 Query Creations

Q2 Pro Create Task

Reference to Video (Subject Invocation)

Q2 Pro Query Creations

Subjects-Reference to Video

Headers

Body parameters

Headers

Path parameters

Response

Headers

Body parameters

Headers

Path parameters

Body parameters

Response

Response

Response