Vidu Q Video Models

Vidu 2.0

Reference to Video

Create Task

POST/ent/v2/reference2video

Subjects-Reference to Video

How to create subjects: [https://platform.vidu.cn/docs/subjects](https://platform.vidu.cn/docs/subjects)

Request Body

modelstring*

Model name
Accepted values: vidu2.0

Query Creations

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

vidu2.0: Fast generation speed

auto_subjectsboolean

Whether to use the intelligent subject library capability. Default is 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 2.0 model, only image subjects and text subjects can be used.

The number of image or text subjects should not exceed 7.

namestring*

Subject name specified by the user. It can be used via [@name] during generation. For example: [@Image1]

imagesstring

Temporary subject images. Up to 3 images.
Note 1: Images can be provided via Base64 encoding or image URLs (make sure they are accessible).Note 2: Images must be in PNG, JPEG, JPG, or WebP format.Note 3: Image dimensions cannot be less than 128*128 pixels, and the aspect ratio must be less than 1:4 or 4:1.Note 4: Please note that the post body of the HTTP request must not exceed , and the encoding must include an appropriate content type string. For example:

promptstring*

Text prompt
A textual description for video generation.
Note 1: The length cannot exceed 5000 characters.
Note 2: Use [@subjects_name] to represent subject content. For example: "@1 and @2 are eating hot pot together, and the narrator says that everyone loves hot pot."

audioboolean

Whether to use the audio-video output capability. Default is false. Accepted values: true, false

true: Use the audio-video output capability.
false: Do not use the audio-video output capability.

durationinteger

Video duration parameter, with default values depending on the model:
vidu2.0: Default is 4 seconds, available option: 4

seedinteger

Random seed

When not passed or passed as 0, a random number will be used instead.
When manually set, the set seed will be used.

aspect_ratiostring

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 parameter, with default values depending on the model and video duration:
vidu2.0 (4s): Default is 360p, available options: 360p, 720p

movement_amplitudestring

Movement amplitude. Default is auto. Accepted values: auto, small, medium, large

payloadstring

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

off_peakboolean

Off peak mode. Default: false. Accepted values:

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

watermarkboolean

Whether to add a watermark.

true: Add watermark.
false: Do not add watermark.
Note 1: Currently the watermark content is fixed as "Content generated by AI", and no watermark is added by default.
Note 2: You can obtain the watermarked video content through the watermarked_url parameter. See the Query Task API for details.

wm_positioninteger

Watermark position. Indicates where the watermark appears on the image. Default: 3. Options:
1: Top left
2: Top right
3: Bottom right
4: Bottom left

wm_urlstring

Watermark content. This is an image URL. When not passed, the default watermark is used: "Content generated by AI".

meta_datastring

Metadata label. A JSON-formatted string. Transparent transmission field. You can customize the format or use the example format as follows:
{
"Label": "your_label", "ContentProducer": "yourcontentproducer", "ContentPropagator": "your_content_propagator", "ProduceID": "yourproductid", "PropagateID": "your_propagate_id", "ReservedCode1": "yourreservedcode1", "ReservedCode2": "your_reserved_code2"
}
When this parameter is empty, the metadata label generated by Vidu is used by default.

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, it will retry the callback three times).
failed: Task failed (if sending fails, it will retry the callback three times).
Vidu uses a callback signature algorithm for verification. See Callback Signature for details.

task_idstring

Task ID generated by Vidu

statestring

Processing state
Accepted values:
created Created successfully
queueing Task in queue
processing Task is being processed
success Task succeeded
failed Task failed

modelstring

The model name used for this call

promptstring

The prompt parameter used for this call

data:image/png;base64,{base64_encode}

videosstring

Temporary subject video. Up to one 5-second video.
Note 1: Only the viduq2-pro Reference to Video model supports video subjects.
Note 2: Up to one 5-second video can be uploaded.
Note 3: Videos must be in MP4, AVI, or MOV format.
Note 4: Video dimensions cannot be less than 128*128 pixels, and the aspect ratio must be less than 1:4 or 4:1.
Note 5: Please note that the byte length after base64 decoding must be less than 20M, and the encoding must include an appropriate content type string. For example:
data:video/mp4;base64,{base64_encode}

voice_idstring

Voice ID
Used to determine the voice timbre in the video. When empty, the system will automatically recommend one. For optional enumeration values, refer to the Voice List.
Or you can use the Voice Cloning API to clone any voice. The voice_id parameters can be used interchangeably.

server_idstring

The subject ID obtained through the Create Subject API.
Note: When server_id is not passed, it is treated as a temporary subject and will not be saved by the system.

imagesstring

The image parameter 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 transparent transmission parameter passed in this call

off_peakboolean

Whether off-peak mode is used in this call

creditsinteger

The credits consumed by this call

watermarkboolean

Whether a watermark is used for this submitted task

created_atstring

Task creation time

Headers

Authorizationstring*

Replace {your api key} with your token

Example:Token {your api key}

Path parameters

idstring*

Task ID. Returned by the Create Task API upon successful creation.

Response

Body parameters

modelstring*

Model name
Accepted values: vidu2.0

vidu2.0: Fast generation speed

imagesstring

Image reference supports multiple images. The model will use the subjects in the images provided in this parameter as references to generate a video with subject consistency. Different model versions support different numbers of reference images. Specific requirements are as follows:
Note 1: The vidu2.0 series models support uploading 1 to 7 images.
Note 2: Images can be provided via Base64 encoding or image URLs (make sure they are accessible).
Note 3: Images must be in PNG, JPEG, JPG, or WebP format.
Note 4: Image dimensions cannot be less than 128*128 pixels, and the aspect ratio must be less than 1:4 or 4:1.
Note 5: Please note that 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}normal

Example:data:image/png

soundsstring

Audio reference supports uploading 1 to 3 audio files. The model will use the audio provided in this parameter as references to generate a video with subject consistency.
Note 1: When using the audio reference feature, up to 3 audio files can be uploaded, and the audio duration ranges from 3-12s.
Note 2: Audio must be in MP3 format.
Note 3: The size of each audio file must not exceed 50M.
Note 4: Please note that the byte length after base64 decoding must be less than 20M, and the encoding must include an appropriate content type string. For base64,{base64_encode}
Note: Only the q3-drama, q3-mix, and q3-ad models support this parameter.normal

Example:data:video/mp3

promptstring*

Text prompt
A textual description for video generation.
Note: The length cannot exceed 5000 characters.

bgmboolean

Whether to add background music to the generated video. Default: false. Acceptable values: true, false.

When true, the system will automatically select suitable music from the preset BGM library and add it; when not passed or false, no BGM is added.
BGM has no time limit and the system automatically adapts to the video duration.
This parameter does not take effect when the duration of the q2 series models is 9 or 10 seconds.
This parameter does not take effect on the q3 series models.

durationinteger

Video duration parameter, with default values depending on the model:
viduq3-drama: Default is 8s, available option: 2-15s
viduq3-ad, viduq3-turbo, viduq3-mix: Default is 5 seconds, available option: 3-15
viduq3: Default is 5 seconds, available option: 3-16
viduq2-pro, viduq2: Default is 5 seconds, available option: 1-10
viduq1: Default is 5 seconds, available option: 5
vidu2.0: Default is 4 seconds, available option: 4

seedinteger

Random seed

When not passed or passed as 0, a random number will be used instead.
When manually set, the set seed will be used.

aspect_ratiostring

Aspect ratio parameter. The q2 and q3 models support any ratio or auto.
viduq3-drama supports 9:16, 16:9
viduq3-ad supports 1:1, 9:16, 16:9, 3:4, 4:3
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.

audioboolean

Whether to use the audio-video output capability. Default is true. Valid values:

false: Do not use audio-video output; outputs silent video.
true: Use audio-synchronized output; outputs video with sound (including dialogue and sound effects).
Note: In non-subject invocation, only the q3 models support this parameter.

movement_amplitudestring

Movement amplitude
Defaults to auto. Accepted values: auto, small, medium, large
Note: The q2 and q3 series models do not support this parameter.

resolutionstring

Resolution parameter, with default values depending on the model and video duration:
vidu2.0 (4s): Default is 360p, available options: 360p, 720p

payloadstring

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

off_peakboolean

Off peak mode. Default: false. Accepted values:

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

watermarkboolean

Whether to add a watermark.

true: Add watermark.
false: Do not add watermark.
Note 1: Currently the watermark content is fixed as "Content generated by AI", and no watermark is added by default.
Note 2: You can obtain the watermarked video content through the watermarked_url parameter. See the Query Task API for details.

wm_positioninteger

Watermark position. Indicates where the watermark appears on the image. Default: 3. Options:
1: Top left
2: Top right
3: Bottom right
4: Bottom left

wm_urlstring

Watermark content. This is an image URL. When not passed, the default watermark is used: "Content generated by AI".

meta_datastring

Metadata label. A JSON-formatted string. Transparent transmission field. You can customize the format or use the example format as follows:
{
"Label": "your_label", "ContentProducer": "your_content_producer", "ContentPropagator": "your_content_propagator", "ProduceID": "your_product_id", "PropagateID": "your_propagate_id", "ReservedCode1": "your_reserved_code1", "ReservedCode2": "your_reserved_code2"
}
When this parameter is empty, the metadata label generated by Vidu is used by default.

callback_urlstring

processing: Task is being processed.
success: Task is completed (if sending fails, it will retry the callback three times).
failed: Task failed (if sending fails, it will retry the callback three times).
Vidu uses a callback signature algorithm for verification. See Callback Signature for details.

200OKapplication/json

Response fields

idstring

Task ID

statestring

Processing state
Accepted values:
created Created successfully
queueing Task in queue
processing Task is being processed
success Task succeeded
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 transparent transmission parameter passed in this task call

bgmboolean

Whether bgm is used in this task call

off_peakboolean

Whether off-peak mode is used in this task call

creationsarray

Generation results

idstring

Generation ID. Used to identify different generations.

urlstring

Generation URL. Valid for 24 hours.

cover_urlstring

Generation cover. Valid for 24 hours.

watermarked_urlstring

Watermarked generation URL. Valid for 24 hours.

200OKapplication/json

Response fields

task_idstring

Task ID generated by Vidu

statestring

Processing state
Accepted values:
created Created successfully
queueing Task in queue
processing Task is being processed
success Task succeeded
failed Task failed

modelstring

The model name used for this call

promptstring

The prompt parameter used for this call

imagesstring

The image parameter 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 transparent transmission parameter passed in this call

off_peakboolean

Whether off-peak mode is used in this call

creditsinteger

The credits consumed by this call

watermarkboolean

Whether a watermark is used for this submitted task

created_atstring

Task creation time

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.com/ent/v2/reference2video' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "vidu2.0",
  "images": "data:image/png",
  "sounds": "data:video/mp3",
  "prompt": "Santa Claus and the bear hug by the lakeside.",
  "bgm": true,
  "duration": 5,
  "seed": 0,
  "aspect_ratio": "3:4",
  "audio": true,
  "movement_amplitude": "string",
  "resolution": "1080p",
  "payload": "string",
  "off_peak": true,
  "watermark": true,
  "wm_position": 0,
  "wm_url": "string",
  "meta_data": "string",
  "callback_url": "string"
}'

200

Response example

{
  "task_id": "your_task_id_here",
  "state": "created",
  "model": "vidu2.0",
  "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"
}

{
  "task_id": "your_task_id_here",
  "state": "created",
  "model": "vidu2.0",
  "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"
}

Features

Get started

About Us

Features

Get started

About Us

Vidu 2.0

Reference to Video

Create Task

Subjects-Reference to Video

Request Body

Query Creations

Response Body

Headers

Path parameters

Response

Body parameters

Response

Search documentation

Features

Get started

About Us

Search documentation

Features

Get started

About Us

Vidu 2.0

Reference to Video

Create Task

Subjects-Reference to Video

Request Body

Query Creations

Response Body

Headers

Path parameters

Response

Body parameters

Response