Moonheart Docs

简体中文

English
ไทย

简体中文

English
ไทย

主题

Vidu ​

Endpoint: POST https://vod.intl.tencentcloudapi.comAction: CreateAigcVideoTask

기본 정보 ​

항목값
ModelNameVidu
ModelVersionq3-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:98–12초; 이미지 1–14장
q3-ad기본 출력: 720P / 1080P
업스케일 출력: 2K / 4K		1:1 / 9:16 / 16:9 / 3:4 / 4:33–16초; 이미지 1–7장
q3-mix———

입력 조건 ​

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

요청 파라미터 ​

파라미터필수타입설명
ModelName필수String고정값 Vidu
ModelVersion선택Stringq3-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선택String480P / 720P / 1080P / 2K / 4K
OutputConfig.Duration선택Integer영상 길이(초)
OutputConfig.AspectRatio선택String16:9 / 9:16 / 1:1 등
OutputConfig.
InputComplianceCheck		선택StringDisabled를 명시적으로 전달하면 입력 심사 해제. 사용 전 영업담당자 문의
OutputConfig.
OutputComplianceCheck		선택StringDisabled를 명시적으로 전달하면 출력 심사 해제. 사용 전 영업담당자 문의

요청 예시 ​

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

json
{
  "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 / 텍스트로 영상 생성 ​

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

응답 예시 ​

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
          }
        }
      ]
    }
  }
}

특수 설정 ​

가드레일 해제 ​

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

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

파라미터해제 값적용 대상
OutputConfig.InputComplianceCheckDisabled입력 심사 해제
OutputConfig.OutputComplianceCheckDisabled출력 심사 해제

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

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

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

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

TTS 모드: 대사와 음색 지정 ​

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\\\":\\\"안녕하세요, 만나서 반갑습니다.\\\",\\\"voice_id\\\":\\\"male-qn-qingse\\\"}\"}",
  "OutputConfig": {
    "StorageMode": "Temporary"
  },
  "SessionContext": "job-001"
}

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

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

버전별 특징 ​

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입니다.

json
{
  "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 형태로 지목합니다.

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

임시 참조 대상 사용 ​

FileInfos의 ObjectId로 참조 대상 이름을 선언하고 프롬프트에서 @ObjectId로 지목합니다. 한 참조 대상에 이미지는 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"
}

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

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

립싱크 (lip-sync) ​

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

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

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

대사와 음색 지정 ​

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 필드:

필드타입기본값설명
voice_idString자동 추천음색 ID
speedFloat1.0말하기 속도. 범위 [0.5, 2]. 값이 클수록 빠름
volumeInteger0음량. 범위 [0, 10]. 0이 기본 음량

참조 오디오 입력 ​

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

이펙트 템플릿 (template_effect) ​

SceneType=template_effect로 지정합니다. ModelVersion은 아무 값이나 넣어도 되며, 실제로 사용할 템플릿은 ExtInfo의 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"
}

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

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

基于 VitePress 构建 · 部署于腾讯云 EdgeOne Pages

© 2026 Moonheart