VOD APILast Updated 2026-09-05

Vidu

On this page

Endpoint: POST https://vod.intl.tencentcloudapi.com
Action: CreateAigcVideoTask

기본 정보

항목	값
ModelName	`Vidu`
ModelVersion	`q3-ad` / `q3-drama` / `q3-mix` / `q3-turbo` / `q3-pro` / `q3` / `q2-pro` / `q2` (`q3-mix`는 참조 전용)
기본값	`ModelVersion=q3-pro` / `Resolution=1080P`
가드레일 해제 지원	지원

버전별 지원 규격

버전	해상도	비율	길이
공통	`480P` / `720P` / `1080P` / `2K` / `4K`	—	—
`q3-drama`	기본 출력: `1080P` 업스케일 출력: `2K` / `4K`	`9:16` / `16:9`	`8–12초`; 이미지 `1–14장`
`q3-ad`	기본 출력: `720P` / `1080P` 업스케일 출력: `2K` / `4K`	`1:1` / `9:16` / `16:9` / `3:4` / `4:3`	`3–16초`; 이미지 `1–7장`
`q3-mix`	—	—	—

입력 조건

버전	조건
`q3-mix`	이미지 참조 / `FileInfos[].Usage=Reference` 여러 컷 구성 / 오디오 동시 생성

요청 파라미터

파라미터	필수	타입	설명
`ModelName`	필수	String	고정값 `Vidu`
`ModelVersion`	선택	String	`q3-ad` / `q3-drama` / `q3-mix` / `q3-turbo` / `q3-pro` / `q3` / `q2-pro` / `q2`. `q3-mix`는 참조 전용
`Prompt`	필수	String	생성 프롬프트
`FileInfos.N`	선택	Array	참조 입력. `Usage`는 `FirstFrame`(첫 프레임) 또는 `Reference`(참조)
`OutputConfig.Resolution`	선택	String	`480P` / `720P` / `1080P` / `2K` / `4K`
`OutputConfig.Duration`	선택	Integer	영상 길이(초)
`OutputConfig.AspectRatio`	선택	String	`16:9` / `9:16` / `1:1` 등
`OutputConfig.` `InputComplianceCheck`	선택	String	`Disabled`를 명시적으로 전달하면 입력 심사 해제. 사용 전 영업담당자 문의
`OutputConfig.` `OutputComplianceCheck`	선택	String	`Disabled`를 명시적으로 전달하면 출력 심사 해제. 사용 전 영업담당자 문의

요청 예시

q3-mix / 이미지로 여러 컷 구성

LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "Vidu",
  "ModelVersion": "q3-mix",
  "FileInfos": [
    {
      "Type": "Url",
      "Category": "Image",
      "Url": "https://example.com/princess.png",
      "Usage": "Reference"
    }
  ],
  "Prompt": "첫 번째 컷: 성 안의 공주가 닫힌 문을 바라봅니다. 두 번째 컷: 공주가 창문을 열고 먼 풍경을 바라보며 미소 짓습니다.",
  "OutputConfig": {
    "StorageMode": "Permanent",
    "MediaName": "Princess scene",
    "Duration": 16,
    "Resolution": "1080P",
    "AspectRatio": "9:16",
    "AudioGeneration": "Enabled"
  },
  "SessionContext": "vidu-reference-001"
}

q3-pro / 텍스트로 영상 생성

LANGUAGE
{
  "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"
}

응답 예시

LANGUAGE
{
  "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
          }
        }
      ]
    }
  }
}

특수 설정

가드레일 해제

입력과 출력 심사를 각각 설정할 수 있습니다.

가드레일 해제 파라미터를 사용하려면 먼저 영업담당자에게 연락해 사용 권한을 확인해야 합니다. 지원 엔진에서도 해당 파라미터를 명시적으로 전달하는 경우에만 가드레일 해제가 적용됩니다. 파라미터를 생략하면 해제되지 않습니다.

파라미터	해제 값	적용 대상
`OutputConfig.InputComplianceCheck`	`Disabled`	입력 심사 해제
`OutputConfig.OutputComplianceCheck`	`Disabled`	출력 심사 해제

다음 설정을 기존 생성 요청에 병합합니다. 입력과 출력 심사를 모두 해제하려면 두 필드를 함께 전달합니다.

LANGUAGE
{
  "OutputConfig": {
    "InputComplianceCheck": "Disabled",
    "OutputComplianceCheck": "Disabled"
  }
}

Avatar: 인물 영상 (디지털 휴먼)

인물 이미지 1장과 음성으로 말하는 인물 영상을 만듭니다. 버전 avatar-q2-pro / avatar-q2-turbo.

TTS 모드: 대사와 음색 지정

LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "Vidu",
  "ModelVersion": "avatar-q2-pro",
  "Prompt": "talking naturally",
  "FileInfos": [
    {
      "Type": "Url",
      "Category": "Image",
      "Url": "https://<cos>/person.png"
    }
  ],
  "ExtInfo": "{\"AdditionalParameters\":\"{\\\"text\\\":\\\"안녕하세요, 만나서 반갑습니다.\\\",\\\"voice_id\\\":\\\"male-qn-qingse\\\"}\"}",
  "OutputConfig": {
    "StorageMode": "Temporary"
  },
  "SessionContext": "job-001"
}

참조 오디오 모드: 오디오 파일 입력

LANGUAGE
{
  "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"
}

버전별 특징

ModelVersion	특징
`q3-ad`	광고 특화. 자동 컷 전환, `5~8초` 숏폼 광고에 적합
`q3-drama`	드라마 특화. 영상과 오디오 동시 생성, 대사와 인물 동선, 카메라 연출이 강함
`q3-mix`	여러 컷 구성 / 오디오 동시 생성
`q3-turbo`	자동 컷 전환과 오디오 동시 생성 지원. 생성 속도가 가장 빠름
`q3-pro`	오디오 포함 고품질 영상 생성
`q3`	자동 컷 전환과 오디오 동시 생성 지원. 멀티 카메라 장면 구성
`q2-pro`	참조 영상 입력, 영상 편집, 영상 교체 지원
`q2`	동적 표현이 좋고 디테일이 풍부
`2.0`	생성 속도 우선 (미출시)
`q1`	화면이 선명하고 전환과 카메라 움직임이 안정적 (미출시)

모드별 지원 버전

모드	지원 버전	비고
텍스트 투 영상	`q3-turbo` / `q3-pro` / `q2` / `q1`	프롬프트 최대 `5000`자
이미지 투 영상	`q3-turbo` / `q3-pro` / `q2-pro-fast` / `q2-pro` / `q2-turbo` / `q1` / `q1-classic` / `2.0`	이미지 `1장`만
첫/끝 프레임	`q3-turbo` / `q3-pro` / `q2-pro-fast` / `q2-pro` / `q2-turbo` / `q1` / `q1-classic` / `2.0`	이미지 `2장`
이미지 참조 생성	`q3-ad` / `q3-drama` / `q3-mix` / `q3-turbo` / `q3` / `q2-pro` / `q2` / `q1` / `2.0`	이미지 여러 장
등록한 인물 / 사물 참조 생성	`q3-turbo` / `q3` / `q2-pro` / `q2` / `q1` / `2.0`	영상 참조 대상는 `q2-pro`만

참조 전용 버전

q3-mix는 참조 이미지의 인물, 사물, 장면을 바탕으로 영상을 생성합니다. 프롬프트에 컷별 동작과 카메라 전환을 적으면 여러 컷을 이어 구성하며 오디오도 함께 생성할 수 있습니다. 참조 이미지는 FileInfos에 Category=Image / Usage=Reference로 전달합니다.

등록한 참조 대상 (SubjectInfos)

같은 인물이나 사물을 여러 태스크에서 재사용할 때 사용합니다. Vidu는 등록한 참조 대상와 임시 참조 대상를 모두 지원합니다.

캐릭터 등록 (CreateAigcSubject)

참조 대상를 미리 등록하고 발급된 ID를 재사용합니다. 비동기 방식이라 태스크를 만들고 DescribeTaskDetail로 조회해야 합니다. 조회 응답의 CreateAigcSubjectTask.Output.SubjectId가 참조 대상 ID입니다.

LANGUAGE
{
  "SubAppId": 1500044236,
  "SubjectName": "Vidu-Obj-Princess",
  "SubjectImages": [
    "https://<cos>/princess.png"
  ],
  "VoiceId": "male-qn-qingse"
}

파라미터	필수	설명
`SubjectName`	필수	참조 대상 이름
`SubjectImages.N`	조건부	참조 이미지. 최대 `3`장. png / jpeg / jpg / webp, 비율 `1:4` ~ `4:1`, `50MB` 이하
`SubjectVideos.N`	조건부	참조 영상. 최대 `1개`, `5`초. mp4 / avi / mov, `128×128` 이상, 비율 `1:4` ~ `4:1`, `100MB` 이하. `q2-pro`만 사용 가능
`VoiceId`	선택	참조 대상 음색 ID. 오디오 동시 생성 태스크에서 사용. 비우면 시스템이 자동 추천

응답의 SubjectId를 저장하세요

참조 대상 ID는 생성 응답이 아니라 DescribeTaskDetail 조회 결과에서 나옵니다. Status가 FINISH이고 ErrCode가 0일 때 CreateAigcSubjectTask.Output.SubjectId를 읽어 보관해야 이후 재사용할 수 있습니다.

등록한 참조 대상 사용

SubjectInfos.N[].Id에 참조 대상 ID, Name에 프롬프트에서 쓸 이름을 지정합니다. 프롬프트에서는 @Name 형태로 지목합니다.

LANGUAGE
{
  "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에는 임시 참조 대상도 함께 넣을 수 있습니다. 이 경우 ImageUrls(최대 3장) 또는 VideoUrls(최대 1개, 5초)를 사용하고, VoiceId로 음색을 지정합니다.

LANGUAGE
{
  "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"
}

임시 참조 대상 사용

FileInfos의 ObjectId로 참조 대상 이름을 선언하고 프롬프트에서 @ObjectId로 지목합니다. 한 참조 대상에 이미지는 1장입니다.

LANGUAGE
{
  "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"
}

@Name 표기와 <<<image_N>>> 표기는 다릅니다

Vidu 프롬프트는 @Name으로 참조 대상를 지정합니다. 엔진별 참조 표기에 맞춰 프롬프트를 작성하세요.

립싱크 (lip-sync)

ModelVersion=lip-sync으로 지정합니다. 사람 얼굴 이미지와 영상, 그리고 음성을 조합해 입 모양을 맞춥니다.

입력	Category	설명
대상 영상	`Video`	입 모양을 맞출 소스 영상
얼굴 이미지	`Image`	대상 인물 얼굴
참조 오디오	`Audio`	입 모양의 기준이 될 음성

음성은 두 가지로 지정합니다. 오디오 파일을 직접 넣거나, Prompt에 대사를 적고 ExtInfo로 음색과 속도 음량을 지정합니다.

대사와 음색 지정

LANGUAGE
{
  "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 필드:

필드	타입	기본값	설명
`voice_id`	String	자동 추천	음색 ID
`speed`	Float	`1.0`	말하기 속도. 범위 `[0.5, 2]`. 값이 클수록 빠름
`volume`	Integer	`0`	음량. 범위 `[0, 10]`. `0`이 기본 음량

참조 오디오 입력

LANGUAGE
{
  "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"
    }
  ]
}

이펙트 템플릿 (template_effect)

SceneType=template_effect로 지정합니다. ModelVersion은 아무 값이나 넣어도 되며, 실제로 사용할 템플릿은 ExtInfo의 template으로 고릅니다.

LANGUAGE
{
  "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"
}

템플릿마다 요구하는 프롬프트가 다릅니다

템플릿별 호출 파라미터와 권장 프롬프트는 Vidu 공식 템플릿 예시 센터에서 확인할 수 있습니다. template_effect는 ModelName=Vidu에서만 동작합니다.