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 时,将返回 24 小时 有效的音频 URL,而非 base64 |
| 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 | 请求标识符 |
调用示例
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)# 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)响应示例
{
"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 必填)。