Vidu API
Debug Console
Dashboard
Docs
Sign in

API REFERENCE

Video Generating

POST https://api.vidu.com/ent/v2/reference2video

Field
Value
Description
Content-Type
application/json
Data Exchange Format
Authorization
Token {your api key}
Replace {} with your API key

Field
Sub Field
Type
Required
Description
model
String
Required
Model name
Accepted values:
viduq3-turbo viduq3 viduq2 viduq1 vidu2.0
- viduq3-turbo: Supports intelligent scene switching and simultaneous audio and video output, boasts the fastest generation speed, and offers the highest cost-effectiveness
- viduq3: Supports intelligent camera switching, supports simultaneous audio and video output, and achieves superior consistency across multiple camera positions
- viduq2: Good dynamic effect and rich generated details
- viduq1: Clear image, smooth transition, stable camera operation
- vidu2.0: Fast generation speed
auto_subjects
Bool
Optional
Whether to use the intelligent entity library capability, default is false, optional values are true and false
- true: Utilize the capabilities of the intelligent agent library.
- false: Do not use the intelligent agent library capability.
subjects
List[Array]
Required
When using the q3, q2, q1, and 2.0 models, only the main body of the image and text can be used
- The maximum number of images or textual content should not exceed 7
When using the q2-pro model, video subjects, text subjects, and image subjects can be employed
- The number of images or textual content should not exceed 4
- The number of video subjects should not exceed 2 (or 1 for temporary video subjects)
Note: viduq3-mix does not support the use of entities for the time being
name
String
Required
Subject name
Usable in prompts via @subjectname
images
Array\{String\}
Required
URLs of images corresponding to the subject.
Each subject supports up to 3 images.
- Assets can be provided via URLs or Base64 encode.
- You must use one of the following codecs: PNG, JPEG, JPG, WebP
- The dimensions of the images must be at least 128x128 pixels
- The aspect ratio of the images must be less than 1:4 or 4:1
- All images are limited to 50MB
- The post body of the HTTP request should not exceed 20MB, and it must include an appropriate content type string. For instance
data:image/png;base64,{base64_encode}
voice_id
String
Optional
Voice ID
Used to determine the voice character in the video. The system will automatically recommend a suitable voice, and optional values can be found in the Voice List. You can also use the Voice Cloning API to clone any voice. The voice_id parameters can be used interchangeably.
prompt
String
Required
Text prompt
A textual description for video generation, with a maximum length of 5000 characters
Or you can use id to represent subject content. For example: 
"@1 and @2 are cooking together, and both say they love hot pot."
audio
Bool
Optional
Whether to enable audio-video output capability. Default is false. Valid values:
- false: Outputs silent video.
- true: Outputs video with generated speech and background music based on the prompt.
By default, audio is set to true for viduq3 and viduq3-turbo, and false for other models
audio_type
String
Optional
Audio type, required when audio is true, defaults to all
-All: Sound effects+vocals
-Speech_only: Vocal only
-Sound-effect_only: Sound effects only
duration
Int
Optional
Video duration parameter, with default values depending on the model:
- viduq3、viduq3-turbo: Default is 5 seconds, available option: 3-16
- 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
seed
Int
Optional
Random seed
- Defaults to a random seed number
- Manually set values will override the default random seed
aspect_ratio
String
Optional
The aspect ratio of the output video
Defaults to 16:9, accepted: 16:9 9:16 1:1
q2、q3 model supports any aspect ratio
resolution
String
Optional
Resolution parameter, with default values depending on the model and video duration:
- viduq3、viduq3-turbo (3 - 16s): Default is 720p, available option: 540p 720p 1080p
- viduq2 (1 - 10s): Default is 720p, available option: 540p 720p 1080p
- viduq1 (5s): Default is 1080p, available option: 1080p
- vidu2.0 (4s): Default is 360p, available options: 360p, 720p
movement_amplitude
String
Optional
The movement amplitude of objects in the frame
Defaults to auto, accepted value: auto small medium large
This parameter does not take effect when using the q2、q3 model
payload
String
Optional
transparent transmission parameters
No processing, only data transmission，with a maximum length of 1048576 characters
off_peak
Bool
Optional
off peak mode, Defaults to false, accepted value: true false
- true：off peak generate mode；
- false：normal generate mode；
- 1：The off_peak mode consumes lower points, please refer to the details Pricing
- 2：Tasks submitted in off peak mode will be generated within 48 hours. Tasks that are not completed will be automatically cancelled and their points will be refunded；
- 3：we also support cancle off_peak tasks.
- 4：The q3 model supports peak-shifting tasks when the audio parameter is true; the q2, q1, and 2.0 series models support peak-shifting tasks when the audio parameter is false
callback_url
String
Optional
Callback
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 GET Generation 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, check out the details here: Callback Signature

Field
Type
Description
task_id
String
Task ID
state
String
It will be returned to a specific processing state:
- created created task successfully
- queueing task in queue
- processing processing
- success generation successful
- failedtask failed
model
String
The parameter of the model used for this call
prompt
String
The text prompt used for this call
images
Array[String]
The images used for this call
duration
Int
The video duration parameter used for this call
seed
Int
The random seed parameter used for this call
aspect_ratio
String
The aspect ratio parameter used for this call
resolution
String
The resolution parameter used for this call
bgm
Bool
Whether to use bgm for this call
audio
Bool
Whether to use audio for this call
audio_type
String
The audio_type parameter used for this call
movement_amplitude
String
The camera movement amplitude parameter used for this call
payload
String
The payload parameter used for this call
off_peak
Bool
The off_peak parameter used for this call
credits
String
The credits used for this call
created_at
String
Task creation time
{
  "task_id": "your_task_id_here",
  "state": "created",
  "model": "viduq3",         
  "prompt": "@1 and @2 are cooking together, and both say they love hot pot.",
  "duration": 8,
  "seed": random_number,
  "resolution": "1080p",
  "movement_amplitude": "auto",
  "payload":"",
  "off_peak": false,
  "credits":credits_number,
  "created_at": "2025-01-01T15:41:31.968916Z"
}

Field
Sub Field
Type
Required
Description
model
String
Required
Model name
Accepted values: viduq3-mix viduq3-turbo viduq3 viduq2-pro viduq2 viduq1 vidu2.0
- viduq3-mix: Strong visual quality, supports intelligent scene transitions, supports simultaneous audio and video output, good dynamic effects, and the strongest balance
- viduq3-turbo: Supports intelligent scene switching and synchronized audio and video output, boasts the fastest generation speed, and offers the highest cost-effectiveness
- viduq3: Supports intelligent camera switching, supports simultaneous audio and video output, and achieves superior consistency across multiple camera positions
- viduq2-pro: Supports video reference, video editing, and video replacement
- viduq2: Good dynamic effect and rich generated details
- viduq1: Clear image, smooth transition, stable camera operation
- vidu2.0: Fast generation speed
images
Array[String]
Optional
The model will use the provided images as references to generate a video with consistent subjects
For fields that accept images:
- viduq3-mix viduq3-turbo viduq3 viduq2 viduq1 vidu2.0 accepts 1 to 7 images.
- viduq2-pro If no video is uploaded, supports 1-7 images ; If Uploading videos, supports 1-4 images.
- Assets can be provided via URLs or Base64 encode.
- You must use one of the following codecs: PNG, JPEG, JPG, WebP
- The dimensions of the images must be at least 128x128 pixels
- The aspect ratio of the images must be less than 1:4 or 4:1
- All images are limited to 50MB
- The length of the base64 decode must be under 10MB, and it must include an appropriate content type string. For instance, data:image/png;base64,\{base64_encode\}
videos
Array[String]
Optional
The video URL corresponding to the subject. All subjects share a 13s duration (each image subject = 1s). Must provide either this or images.
- Note 1: This parameter is only supported by the viduq2-pro model.
- Note 2: When using the video reference feature, supports uploading at most 1 video of 8s or 2 videos of 5s.
- Note 3: Supported video formats: mp4, avi, mov.
- Note 4: Video resolution cannot be less than 128*128, aspect ratio must be between 1:4 and 4:1, and size must not exceed 100M.
- Note 5: Please note that the byte length after base64 decoding must be less than 20M, and the encoding must include the appropriate content type string, e.g.: data:video/mp4;base64,\{base64_encode\}
prompt
String
Required
Text prompt
A textual description for video generation, with a maximum length of 5000 characters
duration
Int
Optional
Video duration parameter, with default values depending on the model:
- viduq3-mix: Default is 5 seconds, available option: 1-16
- viduq3-turbo、viduq3-pro: Default is 5 seconds, available option: 3-16
- viduq2-pro: Default is 5 seconds, available option: 0-10(0 for automatic duration)
- 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
seed
Int
Optional
Random seed
- Defaults to a random seed number
- Manually set values will override the default random seed
aspect_ratio
String
Optional
The aspect ratio of the output video
Defaults to 16:9, accepted: 16:9 9:16``3:4 4:3 1:1
3:4&4:3only support q2 model
resolution
String
Optional
Resolution parameter, with default values depending on the model and video duration:
- viduq3-mix(1-16):Default is 720p, available option: 720p 1080p
- viduq3-turbo、viduq3-pro(3-16):Default is 720p, available option: 540p 720p 1080p
- viduq2-pro (0 - 10s): Default is 720p, available option: 540p 720p 1080p
- viduq2 (1 - 10s): Default is 720p, available option: 540p 720p 1080p
- viduq1 (5s): Default is 1080p, available option: 1080p
- vidu2.0 (4s): Default is 360p, available options: 360p, 720p
movement_amplitude
String
Optional
The movement amplitude of objects in the frame
Defaults to auto, accepted value: auto small medium large
This parameter does not take effect when using the q2 model
bgm
Bool
Optional
Whether to add background music to the generated video.
Default: false. Acceptable values: true, false.
When true, the system will automatically add a suitable BGM.
BGM has no time limit and the system automatically adapts.
BGM does not take effect when the duration of the q2 model is 9 or 10 seconds
q3 model does not support this parameter
payload
String
Optional
transparent transmission parameters
No processing, only data transmission，with a maximum length of 1048576 characters
off_peak
Bool
Optional
off peak mode, Defaults to false, accepted value: true false
- true：off peak generate mode；
- false：normal generate mode；
- 1：The off_peak mode consumes lower points, please refer to the details Pricing
- 2：Tasks submitted in off peak mode will be generated within 48 hours. Tasks that are not completed will be automatically cancelled and their points will be refunded；
- 3：we also support cancle off_peak tasks.
- 4：The q3 model supports peak-shifting tasks when the audio parameter is true; the q2, q1, and 2.0 series models support peak-shifting tasks when the audio parameter is false
callback_url
String
Optional
Callback
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 GET Generation 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, check out the details here: Callback Signature

Field
Type
Description
task_id
String
Task ID
state
String
It will be returned to a specific processing state:
- created created task successfully
- queueing task in queue
- processing processing
- success generation successful
- failedtask failed
model
String
The parameter of the model used for this call
prompt
String
The text prompt used for this call
images
Array[String]
The images used for this call
videos
Array[String]
The videos used for this call
duration
Int
The video duration parameter used for this call
seed
Int
The random seed parameter used for this call
aspect_ratio
String
The aspect ratio parameter used for this call
resolution
String
The resolution parameter used for this call
bgm
Bool
Whether to use bgm for this call
audio
Bool
Whether to use audio for this call
movement_amplitude
String
The camera movement amplitude parameter used for this call
payload
String
The payload parameter used for this call
off_peak
Bool
The off_peak parameter used for this call
credits
String
The credits used for this call
created_at
String
Task creation time
{
  "task_id": "your_task_id_here",
  "state": "created",
  "model": "viduq3-mix",
  "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": "16:9",
  "resolution": "720p",
  "bgm": false,
  "movement_amplitude": "auto",
  "payload":"",
  "off_peak": false,
  "credits": credits_number,
  "created_at": "2025-01-01T15:41:31.968916Z"
}
On this page
Overview
  • Request Address
  • Request Header
  • Subjects-Reference to Video
  • Request Body
  • Response Body
  • Reference to Video
  • Request Body
  • Response Body