Skip to content

Vidu โ€‹

Updated

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 โ€‹

ItemValue
ModelNameVidu
ModelVersionq4-preview / q3-ad / q3-drama / q3-mix / q3-turbo / q3-pro / q3 / q2-pro / q2 (q3-mix is reference-only)
Default valueModelVersion=q3-pro / Resolution=1080P
Guardrail disable supportSupported

Specifications Supported by Version โ€‹

VersionResolutionAspect ratioLength
Common480P / 720P / 1080P / 2K / 4Kโ€”โ€”
q3-dramaDefault output: 1080P
Upscaled output: 2K / 4K
9:16 / 16:98โ€“12 seconds; image 1โ€“14
q3-adDefault output: 720P / 1080P
Upscaled output: 2K / 4K
1:1 / 9:16 / 16:9 / 3:4 / 4:33โ€“16 seconds; image 1โ€“7
q3-mixโ€”โ€”โ€”
q4-preview540P / 720P / 1080P / 2K / 4K1:1 / 9:16 / 16:9 / 3:4 / 4:33โ€“16 seconds; reference images 1โ€“15, reference audio 0โ€“3 clips

Input Conditions โ€‹

VersionConditions
q3-mixImage reference / FileInfos.Usage=Reference
Multiple shot composition / simultaneous audio generation
q4-previewImage to video: exactly 1 image, Usage=FirstFrame as the first frame
Reference 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 โ€‹

ParameterRequiredTypeDescription
ModelNameRequiredStringFixed value Vidu
ModelVersionOptionalStringq4-preview / q3-ad / q3-drama / q3-mix / q3-turbo / q3-pro / q3 / q2-pro / q2. q3-mix is reference-only
PromptRequiredStringGeneration prompt
FileInfos.NOptionalArrayReference input. Category is Image / Audio; Usage is FirstFrame (first frame) or Reference (reference). With multiple references, every file must carry Usage
OutputConfig.ResolutionOptionalString480P / 720P / 1080P / 2K / 4K (q4-preview also supports 540P and does not support 480P)
OutputConfig.DurationOptionalIntegerVideo length (seconds)
OutputConfig.AspectRatioOptionalString16:9 / 9:16 / 1:1, etc.
OutputConfig.AudioGenerationOptionalStringEnabled generates audio together with video; Disabled outputs silent video
OutputConfig.
InputComplianceCheck
OptionalStringPassing Disabled explicitly disables input moderation. Contact your sales representative before use
OutputConfig.
OutputComplianceCheck
OptionalStringPassing 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.

json
{
  "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.

json
{
  "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 โ€‹

json
{
  "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 โ€‹

json
{
  "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 โ€‹

json
{
  "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.

ParameterDisable valueApplies to
OutputConfig.InputComplianceCheckDisabledInput moderation disabled
OutputConfig.OutputComplianceCheckDisabledOutput moderation disabled

Merge the following settings into an existing generation request. To disable both input and output moderation, pass both fields together.

json
{
  "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 โ€‹

json
{
  "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 โ€‹

json
{
  "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 โ€‹

ModelVersionFeatures
q4-previewLower 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-adAdvertising-focused. Automatic shot transitions, suitable for 5~8 seconds short-form ads
q3-dramaDrama-focused. Video and audio generated simultaneously; strong on dialogue, character movement, and camera direction
q3-mixMultiple shot composition / simultaneous audio generation
q3-turboSupports automatic shot transitions and simultaneous audio generation. Fastest generation speed
q3-proHigh-quality video generation including audio
q3Supports automatic shot transitions and simultaneous audio generation. Multi-camera scene composition
q2-proSupports reference video input, video editing, and video replacement
q2Good dynamic expression and rich detail
2.0Generation speed first (unreleased)
q1Clear image with stable transitions and camera movement (unreleased)

Supported Versions by Mode โ€‹

ModeSupported versionsNotes
Text to videoq3-turbo / q3-pro / q2 / q1Prompt up to 5000 characters
Image to videoq4-preview / q3-turbo / q3-pro / q2-pro-fast / q2-pro / q2-turbo / q1 / q1-classic / 2.0Image 1 only
First/last frameq3-turbo / q3-pro / q2-pro-fast / q2-pro / q2-turbo / q1 / q1-classic / 2.0Image 2
Image reference generationq4-preview / q3-ad / q3-drama / q3-mix / q3-turbo / q3 / q2-pro / q2 / q1 / 2.0Multiple images. q4-preview can add 0โ€“3 reference audio clips
Registered person / object reference generationq3-turbo / q3 / q2-pro / q2 / q1 / 2.0Video 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.

json
{
  "SubAppId": 1500044236,
  "SubjectName": "Vidu-Obj-Princess",
  "SubjectImages": [
    "https://<cos>/princess.png"
  ],
  "VoiceId": "male-qn-qingse"
}
ParameterRequiredDescription
SubjectNameRequiredReference subject name
SubjectImages.NConditionalReference images. Up to 3. png / jpeg / jpg / webp, aspect ratio 1:4 ~ 4:1, 50MB or less
SubjectVideos.NConditionalReference 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
VoiceIdOptionalReference 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.

json
{
  "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.

json
{
  "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.

json
{
  "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.

InputCategoryDescription
Target videoVideoSource video whose mouth shapes are matched
Face imageImageFace of the target person
Reference audioAudioVoice 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 โ€‹

json
{
  "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:

FieldTypeDefaultDescription
voice_idStringAutomatic recommendationVoice ID
speedFloat1.0Speaking speed. Range [0.5, 2]. Larger values are faster
volumeInteger0Volume. Range [0, 10]. 0 is the default volume

Reference Audio Input โ€‹

json
{
  "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.

json
{
  "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.

Built with VitePress ยท Deployed on Tencent EdgeOne Pages