Vidu โ
Endpoint: POST https://vod.intl.tencentcloudapi.comAction: CreateAigcVideoTask
Vidu is a video generation model that supports text-to-video, first-frame / first-and-last-frame video generation, and multi-image reference generation (1โ7 images for q3-ad, 1โ14 for q3-drama, 1โ15 images plus 0โ3 audio clips for q4-preview). q3-mix supports multi-shot composition, and it also offers digital humans, lip sync, and effect templates, and can generate audio at the same time.
Basic Information โ
| Item | Value |
|---|---|
| ModelName | Vidu |
| ModelVersion | q4-preview / q3-ad / q3-drama / q3-mix / q3-turbo / q3-pro / q3 / q2-pro / q2 (q3-mix is reference-only) |
| Default value | ModelVersion=q3-pro / Resolution=1080P |
| Guardrail disable support | Supported |
Specifications Supported by Version โ
| Version | Resolution | Aspect ratio | Length |
|---|---|---|---|
| Common | 480P / 720P / 1080P / 2K / 4K | โ | โ |
q3-drama | Default output: 1080PUpscaled output: 2K / 4K | 9:16 / 16:9 | 8โ12 seconds; image 1โ14 |
q3-ad | Default output: 720P / 1080PUpscaled output: 2K / 4K | 1:1 / 9:16 / 16:9 / 3:4 / 4:3 | 3โ16 seconds; image 1โ7 |
q3-mix | โ | โ | โ |
q4-preview | 540P / 720P / 1080P / 2K / 4K | 1:1 / 9:16 / 16:9 / 3:4 / 4:3 | 3โ16 seconds; reference images 1โ15, reference audio 0โ3 clips |
Input Conditions โ
| Version | Conditions |
|---|---|
q3-mix | Image reference / FileInfos.Usage=ReferenceMultiple shot composition / simultaneous audio generation |
q4-preview | Image to video: exactly 1 image, Usage=FirstFrame as the first frameReference to video: 1โ15 images + 0โ3 audio clips, all with Usage=Reference (reference video is not supported)Text-to-video and first/last-frame are not supported Native audio output supported ( AudioGeneration=Enabled) |
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
ModelName | Required | String | Fixed value Vidu |
ModelVersion | Optional | String | q4-preview / q3-ad / q3-drama / q3-mix / q3-turbo / q3-pro / q3 / q2-pro / q2. q3-mix is reference-only |
Prompt | Required | String | Generation prompt |
FileInfos.N | Optional | Array | Reference input. Category is Image / Audio; Usage is FirstFrame (first frame) or Reference (reference). With multiple references, every file must carry Usage |
OutputConfig.Resolution | Optional | String | 480P / 720P / 1080P / 2K / 4K (q4-preview also supports 540P and does not support 480P) |
OutputConfig.Duration | Optional | Integer | Video length (seconds) |
OutputConfig.AspectRatio | Optional | String | 16:9 / 9:16 / 1:1, etc. |
OutputConfig.AudioGeneration | Optional | String | Enabled generates audio together with video; Disabled outputs silent video |
OutputConfig.InputComplianceCheck | Optional | String | Passing Disabled explicitly disables input moderation. Contact your sales representative before use |
OutputConfig.OutputComplianceCheck | Optional | String | Passing Disabled explicitly disables output moderation. Contact your sales representative before use |
Request Examples โ
q4-preview / First-Frame Image to Video โ
Pass exactly 1 image and declare it as the first frame with Usage=FirstFrame. q4-preview does not support text-only generation, so an image is required.
{
"SubAppId": 123456789,
"ModelName": "Vidu",
"ModelVersion": "q4-preview",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/first-frame.png",
"Usage": "FirstFrame"
}
],
"Prompt": "the girl turns around and smiles at the camera, soft wind moves her hair",
"OutputConfig": {
"StorageMode": "Temporary",
"Duration": 5,
"Resolution": "1080P",
"AspectRatio": "16:9",
"AudioGeneration": "Enabled"
},
"SessionContext": "vidu-q4-i2v-001"
}q4-preview / Multi-Image + Audio Reference to Video โ
Use 1โ15 images and 0โ3 audio clips, each with Usage=Reference. Reference video input is not supported.
{
"SubAppId": 123456789,
"ModelName": "Vidu",
"ModelVersion": "q4-preview",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/character.png",
"Usage": "Reference"
},
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/scene.png",
"Usage": "Reference"
},
{
"Type": "Url",
"Category": "Audio",
"Url": "https://<cos>/voice.mp3",
"Usage": "Reference"
}
],
"Prompt": "the character walks into the scene and speaks to the camera, lip movement follows the reference audio",
"OutputConfig": {
"StorageMode": "Temporary",
"Duration": 8,
"Resolution": "720P",
"AspectRatio": "9:16",
"AudioGeneration": "Enabled"
},
"SessionContext": "vidu-q4-ref-001"
}q3-mix / Composing Multiple Shots with Images โ
{
"SubAppId": 123456789,
"ModelName": "Vidu",
"ModelVersion": "q3-mix",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://example.com/princess.png",
"Usage": "Reference"
}
],
"Prompt": "Shot 1: A princess inside a castle looks at a closed door. Shot 2: The princess opens the window, gazes at the distant scenery and smiles.",
"OutputConfig": {
"StorageMode": "Permanent",
"MediaName": "Princess scene",
"Duration": 16,
"Resolution": "1080P",
"AspectRatio": "9:16",
"AudioGeneration": "Enabled"
},
"SessionContext": "vidu-reference-001"
}q3-pro / Generating Video from Text โ
{
"SubAppId": 123456789,
"ModelName": "Vidu",
"ModelVersion": "q3-pro",
"Prompt": "a calm sunset over the ocean, cinematic",
"OutputConfig": {
"Resolution": "1080P",
"Duration": 5,
"AspectRatio": "16:9",
"StorageMode": "Temporary"
},
"SessionContext": "job-001"
}Response Example โ
{
"AigcVideoTask": {
"Status": "FINISH",
"ErrCode": 0,
"Progress": 100,
"Output": {
"FileInfos": [
{
"FileUrl": "http://<host>.vod2.myqcloud.com/.../aigcVideoGenFile.mp4",
"ExpireTime": "2026-08-01T10:29:48Z",
"MetaData": {
"Width": 1920,
"Height": 1080,
"Duration": 5.07,
"Container": "mov,mp4,m4a",
"Bitrate": 9494850
}
}
]
}
}
}Special Settings โ
Guardrail Disable โ
Input and output moderation can be configured separately.
To use the guardrail disable parameters, first contact your sales representative to confirm usage permission. Even on supported engines, guardrails are disabled only when the corresponding parameter is passed explicitly. If the parameter is omitted, guardrails are not disabled.
| Parameter | Disable value | Applies to |
|---|---|---|
OutputConfig.InputComplianceCheck | Disabled | Input moderation disabled |
OutputConfig.OutputComplianceCheck | Disabled | Output moderation disabled |
Merge the following settings into an existing generation request. To disable both input and output moderation, pass both fields together.
{
"OutputConfig": {
"InputComplianceCheck": "Disabled",
"OutputComplianceCheck": "Disabled"
}
}Avatar: Human Video (Digital Human) โ
Creates a human video that speaks using the person image 1 and a voice. Versions avatar-q2-pro / avatar-q2-turbo.
TTS Mode: Specifying Dialogue and Voice โ
{
"SubAppId": 123456789,
"ModelName": "Vidu",
"ModelVersion": "avatar-q2-pro",
"Prompt": "talking naturally",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/person.png"
}
],
"ExtInfo": "{\"AdditionalParameters\":\"{\\\"text\\\":\\\"Hello, nice to meet you.\\\",\\\"voice_id\\\":\\\"male-qn-qingse\\\"}\"}",
"OutputConfig": {
"StorageMode": "Temporary"
},
"SessionContext": "job-001"
}Reference Audio Mode: Audio File Input โ
{
"SubAppId": 123456789,
"ModelName": "Vidu",
"ModelVersion": "avatar-q2-turbo",
"Prompt": "talking naturally",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/person.png"
},
{
"Type": "Url",
"Category": "Audio",
"Url": "https://<cos>/voice.mp3"
}
],
"OutputConfig": {
"StorageMode": "Temporary"
},
"SessionContext": "job-001"
}Features by Version โ
| ModelVersion | Features |
|---|---|
q4-preview | Lower cost; expressive acting, synchronized audio and video, strong shot tension and effects. Supports first-frame image-to-video and multi-image + audio reference; no text-to-video or first/last-frame |
q3-ad | Advertising-focused. Automatic shot transitions, suitable for 5~8 seconds short-form ads |
q3-drama | Drama-focused. Video and audio generated simultaneously; strong on dialogue, character movement, and camera direction |
q3-mix | Multiple shot composition / simultaneous audio generation |
q3-turbo | Supports automatic shot transitions and simultaneous audio generation. Fastest generation speed |
q3-pro | High-quality video generation including audio |
q3 | Supports automatic shot transitions and simultaneous audio generation. Multi-camera scene composition |
q2-pro | Supports reference video input, video editing, and video replacement |
q2 | Good dynamic expression and rich detail |
2.0 | Generation speed first (unreleased) |
q1 | Clear image with stable transitions and camera movement (unreleased) |
Supported Versions by Mode โ
| Mode | Supported versions | Notes |
|---|---|---|
| Text to video | q3-turbo / q3-pro / q2 / q1 | Prompt up to 5000 characters |
| Image to video | q4-preview / q3-turbo / q3-pro / q2-pro-fast / q2-pro / q2-turbo / q1 / q1-classic / 2.0 | Image 1 only |
| First/last frame | q3-turbo / q3-pro / q2-pro-fast / q2-pro / q2-turbo / q1 / q1-classic / 2.0 | Image 2 |
| Image reference generation | q4-preview / q3-ad / q3-drama / q3-mix / q3-turbo / q3 / q2-pro / q2 / q1 / 2.0 | Multiple images. q4-preview can add 0โ3 reference audio clips |
| Registered person / object reference generation | q3-turbo / q3 / q2-pro / q2 / q1 / 2.0 | Video reference subject q2-pro only |
Reference-Only Version
q3-mix generates video based on the people, objects, and scenes in reference images. If you write per-shot actions and camera transitions in the prompt, it composes multiple shots in sequence and can also generate audio. Reference images are passed to FileInfos as Category=Image / Usage=Reference.
Registered Reference Subjects (SubjectInfos) โ
Used when reusing the same person or object across multiple tasks. Vidu supports both registered reference subjects and temporary reference subjects.
Character Registration (CreateAigcSubject) โ
Register a reference subject in advance and reuse the issued ID. Because it is asynchronous, you must create a task and then query it with DescribeTaskDetail. The CreateAigcSubjectTask.Output.SubjectId of the query response is the reference subject ID.
{
"SubAppId": 1500044236,
"SubjectName": "Vidu-Obj-Princess",
"SubjectImages": [
"https://<cos>/princess.png"
],
"VoiceId": "male-qn-qingse"
}| Parameter | Required | Description |
|---|---|---|
SubjectName | Required | Reference subject name |
SubjectImages.N | Conditional | Reference images. Up to 3. png / jpeg / jpg / webp, aspect ratio 1:4 ~ 4:1, 50MB or less |
SubjectVideos.N | Conditional | Reference video. Up to 1, 5 seconds. mp4 / avi / mov, 128ร128 or more, aspect ratio 1:4 ~ 4:1, 100MB or less. Only q2-pro can be used |
VoiceId | Optional | Reference subject voice ID. Used in tasks that generate audio simultaneously. Leave empty for automatic system recommendation |
Save the SubjectId from the Response
The reference subject ID does not come from the generation response but from the DescribeTaskDetail query result. When Status is FINISH and ErrCode is 0 days, read and store CreateAigcSubjectTask.Output.SubjectId so it can be reused later.
Using Registered Reference Subjects โ
Specify the reference subject ID in SubjectInfos.N.Id and the name to use in the prompt in Name. In the prompt, refer to it in the @Name form.
{
"SubAppId": 123456789,
"ModelName": "Vidu",
"ModelVersion": "q2-pro",
"SubjectInfos": [
{
"Id": "940599910921682944",
"Name": "Princess"
},
{
"Id": "940599790679379968",
"Name": "Prince"
}
],
"Prompt": "@Princess holds hands with @Prince and runs out into the meadow",
"OutputConfig": {
"Duration": 10,
"Resolution": "720P",
"AspectRatio": "9:16",
"AudioGeneration": "Enabled",
"StorageMode": "Permanent"
},
"SessionContext": "job-001"
}SubjectInfos can also include temporary reference subjects. In that case, use ImageUrls (up to 3) or VideoUrls (up to 1, 5 seconds), and specify the voice with VoiceId.
{
"SubAppId": 123456789,
"ModelName": "Vidu",
"ModelVersion": "q3-turbo",
"SubjectInfos": [
{
"Name": "Narrator",
"VoiceId": "male-qn-badao",
"ImageUrls": [
"https://<cos>/narrator.png"
]
}
],
"Prompt": "@Narrator walks into the frame and starts speaking",
"OutputConfig": {
"Duration": 8,
"Resolution": "1080P",
"AudioGeneration": "Enabled",
"StorageMode": "Temporary"
},
"SessionContext": "job-001"
}Using Temporary Reference Subjects โ
With FileInfos, declare the reference subject name in ObjectId, and refer to it as @ObjectId in the prompt. The images for one reference subject are limited to 1.
{
"SubAppId": 123456789,
"ModelName": "Vidu",
"ModelVersion": "q3-turbo",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/princess.png",
"ObjectId": "Princess"
},
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/prince.jpg",
"ObjectId": "Prince"
}
],
"Prompt": "@Princess holds hands with @Prince and runs out into the meadow",
"OutputConfig": {
"Duration": 10,
"Resolution": "720P",
"AspectRatio": "9:16",
"AudioGeneration": "Enabled",
"StorageMode": "Permanent"
},
"SessionContext": "job-001"
}The @Name Notation and the <<<image_N>>> Notation Differ
The Vidu prompt specifies the reference subject with @Name. Write the prompt to match the reference notation of each engine.
Lip Sync (lip-sync) โ
Specified with ModelVersion=lip-sync. It combines a human face image, a video, and a voice so the mouth shapes match.
| Input | Category | Description |
|---|---|---|
| Target video | Video | Source video whose mouth shapes are matched |
| Face image | Image | Face of the target person |
| Reference audio | Audio | Voice used as the basis for mouth shapes |
The voice is specified in one of two ways: put an audio file directly, or write the dialogue in Prompt and specify the voice, speed, and volume with ExtInfo.
Specifying Dialogue and Voice โ
{
"SubAppId": 123456789,
"ModelName": "Vidu",
"ModelVersion": "lip-sync",
"FileInfos": [
{
"Type": "Url",
"Category": "Video",
"Url": "https://<cos>/source.mp4"
},
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/face.png"
}
],
"Prompt": "lets dance and sing with me",
"ExtInfo": "{\"AdditionalParameters\": \"{\\\"voice_id\\\": \\\"male-qn-qingse\\\", \\\"volume\\\": 5, \\\"speed\\\": 1}\"}",
"OutputConfig": {
"StorageMode": "Temporary"
},
"SessionContext": "job-001"
}ExtInfo.AdditionalParameters fields:
| Field | Type | Default | Description |
|---|---|---|---|
voice_id | String | Automatic recommendation | Voice ID |
speed | Float | 1.0 | Speaking speed. Range [0.5, 2]. Larger values are faster |
volume | Integer | 0 | Volume. Range [0, 10]. 0 is the default volume |
Reference Audio Input โ
{
"SubAppId": 123456789,
"ModelName": "Vidu",
"ModelVersion": "lip-sync",
"FileInfos": [
{
"Type": "Url",
"Category": "Video",
"Url": "https://<cos>/source.mp4"
},
{
"Type": "Url",
"Category": "Audio",
"Url": "https://<cos>/voice.mp3"
},
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/face.png"
}
]
}Effect Template (template_effect) โ
Specified with SceneType=template_effect. ModelVersion accepts any value; the template actually used is selected in ExtInfo through template.
{
"SubAppId": 123456789,
"ModelName": "Vidu",
"ModelVersion": "q2-turbo",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/subject.png"
}
],
"Prompt": "the subject suddenly explodes into fine particles",
"SceneType": "template_effect",
"ExtInfo": "{\"AdditionalParameters\": \"{\\\"template\\\": \\\"morphlab\\\"}\"}",
"OutputConfig": {
"StorageMode": "Temporary"
},
"SessionContext": "job-001"
}Each Template Requires a Different Prompt
The call parameters and recommended prompts for each template can be found in the Vidu official template example center. template_effect works only in ModelName=Vidu.