AI Dubbing

이 문서는 Tencent Cloud 공식 문서 AI Dubbing Integration을 참고합니다.

AI 음성 합성(TTS)과 음성 클로닝을 제공합니다. 오디오북, 팟캐스트, 영상 더빙 등에 사용하며 40개 이상의 언어를 지원합니다. 동기 API(SyncDubbing)는 클로닝과 단문 합성을 즉시 처리하고, 비동기 API(ProcessMedia)는 장문 합성(TextToSpeech)과 화자 교체(SpeechToSpeech)를 처리합니다.

API 정보

항목	값
서비스	MPS
API Action	`SyncDubbing`(clone/tts), `ProcessMedia`(async-tts/async-sts)
엔드포인트	`mps.tencentcloudapi.com`
API 버전	`2019-06`-12
처리 방식	비동기 (TaskId 발급 후 결과 조회)

인증은 모든 API가 공통으로 TC3-HMAC-SHA256(SecretId/SecretKey) 서명을 사용합니다. 서명 생성 방법은 Quick Start의 TokenHub 문서를 참고하세요.

결과 조회는 DescribeTaskDetail 또는 완료 콜백으로 받을 수 있습니다.

SyncDubbing (clone / tts)

파라미터	타입	필수	예시	설명
Text	String	tts 시 필수	`Hello, welcome!`	합성할 텍스트. 동기 모드는 `2000`자 이하
TextLang	String	선택	`en`	텍스트 언어. 기본 `zh`. 아래 언어 표 참조
VoiceId	String	tts 시 필수	`v1_Pi1pR9Q9UHqVOrQ0YpZFwL+Q/...`	음성 ID. 시스템 음성 또는 clone 모드가 반환한 VoiceId
AudioData	String	clone 시 필수(택일)	base64 문자열	클로닝 오디오 base64. WAV/MP3/MP4 등 지원
AudioUrl	String	clone 시 필수(택일)	`https://example.com/voice.wav`	클로닝 오디오 URL. AudioData와 택일
AudioLang	String	선택	`zh`	클로닝 오디오 언어. 기본 `zh`
ExtParam	String	선택	`{"synExt":{"sampleRate":44100,"pitch":2},"cloneExt":{"timeRanges":[[5.2,20]]}}`	확장 파라미터(JSON 문자열). synExt: `sampleRate` / `pitch` / `duration`, cloneExt: `timeRanges`(초 단위 [start, end] 목록)
Output.OutputType	String	선택	`URL`	`URL` 지정 시 base64 대신 `24시간` 유효한 오디오 URL 반환
ResourceId	String	선택	-	리소스 ID. 기본값은 계정의 주 리소스 ID

ProcessMedia (async-tts / async-sts)

파라미터	타입	필수	예시	설명
InputInfo	Object	필수	`{"Type":"URL","UrlInputInfo":{"Url":"https://example.com/video.mp4"}}`	async-sts는 실제 입력 미디어. async-tts는 접근 가능한 URL이면 placeholder로 사용 가능
OutputStorage	Object	필수	`{"Type":"COS","CosOutputStorage":{"Bucket":"mybucket-125xxx","Region":"ap-guangzhou"}}`	출력 COS 저장소. 비동기 모드는 COS 필수
OutputDir	String	필수	`/output/dubbing/`	출력 디렉터리. `/`로 시작하고 `/`로 끝나야 함
AiAnalysisTask.Definition	Integer	필수	`36`	더빙 태스크 템플릿 ID. 고정값 `36`
AiAnalysisTask.ExtendedParameter	String	필수	`{"dubbing":{"dubbingType":"TextToSpeech","text":"...","voiceId":"v1_..."}}`	더빙 설정(JSON 문자열). 아래 표 참조
TaskNotifyConfig.NotifyUrl	String	선택	`https://example.com/callback`	태스크 완료 콜백 URL. NotifyType은 `URL`

ExtendedParameter의 dubbing 객체 필드는 다음과 같습니다.

파라미터	타입	필수	예시	설명
dubbingType	String	필수	`TextToSpeech`	`TextToSpeech`(장문 TTS) 또는 `SpeechToSpeech`(화자 교체)
text	String	TextToSpeech 시 필수	`긴 텍스트...`	합성할 텍스트
textLang	String	선택	`zh`	텍스트 언어
voiceId	String	조건부 필수	`v1_Pi1pR9Q9UHqVOrQ0YpZFwL+Q/...`	음성 ID. SpeechToSpeech에서는 voiceId 또는 cloneVideoUrl 중 하나 필수
cloneVideoUrl	String	조건부 필수	`https://example.com/train.mp4`	클로닝할 영상/오디오 URL. `5초` 이상, 단일 화자
cloneVideoLang	String	선택	`zh`	클로닝 영상/오디오 언어
srcLang	String	선택	`zh`	원본 영상/오디오 언어(SpeechToSpeech)
outputPattern	String	선택	`{taskType}-{timestamp}`	출력 파일명 접두사. `{taskType}`, `{timestamp}` 플레이스홀더 지원
extraPara.synExt	Object	선택	`{"pitch":2,"sampleRate":44100}`	음질 파라미터. `pitch`는 -12~`12`, `sampleRate`는 `8000` / `16000`(기본) / `22050` / `32000` / 44100. sampleRate는 TTS에서 사용

지원 언어 코드(일부): zh / en / ja / ko / de / fr / es / it / ru / pt / ar / hi / th / vi / id / ms / tr / nl / pl / sv / fi / yue / he / fa 등 40개 이상.

SyncDubbing

파라미터	타입	필수	예시	설명
ErrorCode	Integer	항상	`0`	처리 결과 코드. `0`이면 성공
Msg	String	항상	`success`	결과 메시지
VoiceId	String	clone 시	`v1_Pi1pR9Q9UHqVOrQ0YpZFwL+Q/...`	발급된 음성 ID. 이후 tts/async 모드에서 사용
AudioData	String	tts 시(택일)	base64 문자열	합성된 오디오 base64. OutputType 미지정 시 반환
AudioUrl	String	tts 시(택일)	`https://...`	합성 오디오 URL. OutputType=URL 지정 시 반환, `24시간` 유효
RequestId	String	항상	`3c140219-cfe9-470e-b241-907877d6fb03`	요청 식별자

ProcessMedia

파라미터	타입	필수	예시	설명
TaskId	String	항상	`2600011633-WorkflowTask-xxxxx`	발급된 태스크 ID. 결과 조회에 사용
RequestId	String	항상	`3c140219-cfe9-470e-b241-907877d6fb03`	요청 식별자

호출 예시

python

import json
from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.mps.v20190612 import mps_client, models

cred = credential.Credential("<SecretId>", "<SecretKey>")
http_profile = HttpProfile
http_profile.endpoint = "mps.tencentcloudapi.com"
client = mps_client.MpsClient(cred, "ap-guangzhou", ClientProfile(httpProfile=http_profile))

# tts 모드: 텍스트 + VoiceId로 동기 합성
params = {
    "Text": "Hello, welcome to Tencent Cloud voice synthesis!",
    "TextLang": "en",
    "VoiceId": "v1_Pi1pR9Q9UHqVOrQ0YpZFwL+Q/...",
    "ExtParam": json.dumps({"synExt": {"sampleRate": 44100, "pitch": 0}})
}

req = models.SyncDubbingRequest
req.from_json_string(json.dumps(params))
resp = client.SyncDubbing(req)
print(resp.to_json_string)

python

# async-sts 모드: 영상 화자 교체 (ProcessMedia, Definition=36)
params = {
    "InputInfo": {
        "Type": "URL",
        "UrlInputInfo": {"Url": "https://example.com/video.mp4"}
    },
    "OutputStorage": {
        "Type": "COS",
        "CosOutputStorage": {"Bucket": "mybucket-125xxx", "Region": "ap-guangzhou"}
    },
    "OutputDir": "/output/sts/",
    "AiAnalysisTask": {
        "Definition": 36,
        "ExtendedParameter": json.dumps({
            "dubbing": {
                "dubbingType": "SpeechToSpeech",
                "voiceId": "v1_Pi1pR9Q9UHqVOrQ0YpZFwL+Q/...",
                "srcLang": "zh"
            }
        })
    }
}

req = models.ProcessMediaRequest
req.from_json_string(json.dumps(params))
resp = client.ProcessMedia(req)
print(resp.to_json_string)

응답 예시

json

{
  "ErrorCode": 0,
  "Msg": "success",
  "AudioData": "UklGRiQAAABXQVZFZm10...",
  "RequestId": "3c140219-cfe9-470e-b241-907877d6fb03"
}

사용 안내

clone 모드가 반환한 전체 VoiceId를 사용합니다. v1_ 접두사로 시작하는 80자 이상의 암호화 base64 값입니다.

async-tts의 InputInfo에는 접근 가능한 URL을 지정합니다. OutputDir는 /로 시작하고 끝나도록 지정하고, 출력 COS Bucket을 설정합니다.

모드 선택 기준: VoiceId 발급이 필요하면 clone(오디오 필수), 2000자 이하 단문 합성은 tts(VoiceId 필수), 장문 합성은 async-tts, 기존 오디오/영상의 화자 교체는 async-sts(실제 입력과 voiceId 또는 cloneVideoUrl 필수)입니다.

AI Dubbing ​

API 정보 ​

SyncDubbing (clone / tts) ​

ProcessMedia (async-tts / async-sts) ​

SyncDubbing ​

ProcessMedia ​

호출 예시 ​

응답 예시 ​

사용 안내 ​