TTS-ElevenLabs
本文整理 MPS 上调用 ElevenLabs 模型族的接口用法。ElevenLabs 在 MPS 里以引擎代号 tts-l1 接入:接口、鉴权、计费、任务查询、存储全部沿用 MPS 既有的语音接口,只在扩展参数 ExtParam 里写 "engine": "tts-l1" 切到 ElevenLabs,再按需带上引擎专属参数。
接口与官网文档
以下接口均属于 MPS「Media AI – Dubbing APIs」,官网接口地址统一在腾讯云国际站 Media AI – Dubbing APIs 目录下。
语音合成与音色
| 接口 | 作用 | 调用方式 | 走 ElevenLabs | 官网接口地址 |
|---|---|---|---|---|
TextToSpeech | 短文本转语音(≤ 2000 字符),直接返回音频 | 同步 | ✅ engine: tts-l1 | 1041/82311 |
TextToSpeechAsync | 长文本转语音,返回 TaskId;可先翻译再合成 | 异步 | ✅ engine: tts-l1 | 1041/79693 |
DescribeTextToSpeechAsyncTask | 查询异步合成结果(Status / AudioUrl) | 同步 | 跟随任务 | 1041/79696 |
CloneVoice | 用一段参考音频克隆音色,返回可复用的 VoiceId | 同步 | ✅ engine: tts-l1 | 1041/82312 |
DesignVoiceAsync | 用文字描述设计新音色,返回 TaskId | 异步 | ✅ engine: tts-l1 | 1041/79694 |
DescribeDesignTask | 查询音色设计结果(VoiceId / 试听音频) | 同步 | 跟随任务 | 1041/79598 |
DescribeVoices | 按类型、性别、年龄、语言、标签筛选可用音色 | 同步 | ✅ 查 ElevenLabs 音色需带 engine | 1041/79695 |
同目录的其它接口
| 接口 | 作用 | 调用方式 | 走 ElevenLabs | 官网接口地址 |
|---|---|---|---|---|
UpdateVoice | 修改克隆/设计音色的名称、描述、性别、年龄、语言、标签、场景、试听音频 | 同步 | ⏳ 接入指引未列出 | 1041/81214 |
DeleteVoice | 删除克隆/设计的音色(释放 100 个配额) | 同步 | ⏳ 接入指引未列出 | 1041/81215 |
ChangeVoice | 音色转换:把输入音频换成指定 VoiceId 的音色 | 同步 | ⏳ 接入指引未列出 | 1041/83750 |
SyncDubbing | 早期合一接口:一次请求完成克隆或合成 | 同步 | ⏳ 接入指引未列出 | 1041/77775 |
✅ = 《TTS-L1 引擎接入指引》明确支持 engine: "tts-l1";⏳ = 这几个接口同样带 ExtParam 字段,但接入指引没有写到 TTS-L1,是否可切到 ElevenLabs 以实际调用为准。
公共约定:
- 版本号
2019-06-12;接入域名国际站mps.intl.tencentcloudapi.com(中国站mps.tencentcloudapi.com)。 - 鉴权统一 TC3-HMAC-SHA256(SecretId / SecretKey),签名方法见 Quick Start。
- 每个接口频率上限
20 次/秒。
与 AI Dubbing 的分工
| 场景 | 用哪篇 |
|---|---|
| 已有文本,要一段音频(配音、有声书、播客、口播) | 本文(TTS) |
| 已有视频/音频,要整段换语言或替换说话人 | AI Dubbing |
| 需要按脚本重录,但音色必须与原说话人一致 | 本文的音色克隆 + TTS |
引擎切换:通过 ExtParam 调用外部引擎
MPS 的语音接口是引擎无关的:Text、VoiceId、TextLang、Output 这些顶层参数对所有引擎都一样,换引擎不换接口、不换鉴权,只看 ExtParam.engine。
TextToSpeech / TextToSpeechAsync / CloneVoice / DesignVoiceAsync / DescribeVoices
│
├─ ExtParam 不带 engine ─────────► MPS 默认引擎
│
└─ ExtParam.engine = "tts-l1" ──► ElevenLabs
│
├─ synExt.* MPS 抽象过的参数(model / format / speed / sampleRate …)
└─ synExt.engineCustom.* 原样透传给 ElevenLabs 的原生参数ExtParam 是 JSON 字符串(不是对象),放进请求体时要二次转义。最小写法:
{ "engine": "tts-l1" }参数分层与优先级:
| 层 | 位置 | 说明 |
|---|---|---|
| 引擎选择 | ExtParam.engine | 填 tts-l1 走 ElevenLabs;不填走 MPS 默认引擎 |
| MPS 统一参数 | ExtParam.synExt.* | format、sampleRate、duration 这类跨引擎通用字段 |
| 引擎专属参数 | ExtParam.synExt.model、speed | 由 TTS-L1 定义,见下一节 |
| 原生透传参数 | ExtParam.synExt.engineCustom.* | 直接透传 ElevenLabs 请求参数,字段名与 ElevenLabs 完全一致 |
同名参数外层优先。 synExt.speed 与 synExt.engineCustom.speed 同时存在时,用外层的 synExt.speed。所以能在 synExt 里表达的参数写在 synExt,只有 ElevenLabs 独有、MPS 未抽象的参数才放进 engineCustom。
还要注意两点:
- 音色 ID 跟引擎绑定。 用
tts-l1克隆/设计出来的VoiceId,合成时也要带engine: "tts-l1";DescribeVoices不带engine查到的是全量音色池,拿去 TTS-L1 合成可能不认。 - 拼错的键不会报错。
ExtParam里写了引擎不认识的键,多数情况被静默忽略,返回一段"能听但不对"的音频。
TTS-L1 引擎主要参数
以下来自《TTS-L1 引擎接入指引》,只在 engine: "tts-l1" 时生效,适用于 TextToSpeech 与 TextToSpeechAsync。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| engine | String | 是 | 固定 tts-l1 |
| synExt.model | String | 否 | 模型,默认 tts-l1-multilingual_v2。可选值见模型列表 |
| synExt.format | String | 否 | 输出格式:mp3 / wav / opus / alaw / ulaw,默认 wav |
| synExt.speed | Float | 否 | 语速,默认 1.0 原速,支持 [0.7, 1.2] |
| synExt.engineCustom | Object | 否 | ElevenLabs 原生参数透传容器 |
| synExt.engineCustom.with_timestamps | Bool | 否 | 返回字符级时间戳(见对齐) |
synExt 里还有官网列出的 MPS 通用字段:sampleRate(8000 / 16000 / 22050 / 24000 / 32000 / 44100,默认 16000)、duration(目标时长,秒)。注意 MPS 默认引擎的 format 只支持 wav / mp3,opus / alaw / ulaw 是 TTS-L1 独有。
engineCustom 里可以放任意 ElevenLabs 语音合成请求参数,字段定义见 ElevenLabs 官网 Text to Speech API。常用三类:
{
"voice_settings": {
"stability": 0.5,
"similarity_boost": 0.75,
"style": 0.0,
"use_speaker_boost": true
},
"previous_text": "上一段的最后一句",
"next_text": "下一段的第一句"
}voice_settings控制表达稳定性与音色还原度:stability越低起伏越大、越"有戏",越高越平稳;use_speaker_boost提升与原音色的相似度。previous_text/next_text提供上下文,让多次请求之间语气连贯 —— 分段合成整篇文稿时必用,否则每段都像重新起头。
TTS-L1 模型列表
| 模型 | 说明 |
|---|---|
tts-l1-multilingual_v2 | 默认。多语言 + 情感表达均衡,通用首选 |
tts-l1-v3 | v3 系列,表现力更强,适合解说、角色化 |
tts-l1-v4 | v4 系列,较新,可用性以账号权限为准 |
tts-l1-v4_turbo | v4 低延迟版,适合实时/高并发 |
tts-l1-turbo_v2_5 | 低延迟版,长文本批量合成性价比高 |
tts-l1-flash_v2_5 | 最低延迟,适合交互式场景,音质要求放宽时用 |
命名规则是 tts-l1- + ElevenLabs 模型名后缀(multilingual_v2 ↔ eleven_multilingual_v2,turbo_v2_5 ↔ eleven_turbo_v2_5),各模型能力见 ElevenLabs 官网 Models。具体哪些模型在你的账号/区域可用,以实际调用返回为准 —— 不同账号开通的模型范围可能不同。
返回与 ExtInfo
| 参数 | 类型 | 说明 |
|---|---|---|
| ErrorCode | Integer | 0 成功 |
| Msg | String | 结果消息 |
| AudioData | String | 音频 base64(未指定 Output.OutputType=URL 时返回) |
| AudioUrl | String | 音频 URL,24 小时内有效 |
| ExtInfo | String | 扩展信息 JSON 字符串,见下表 |
ExtInfo 解析后:
| 字段 | 类型 | 说明 |
|---|---|---|
| duration | Float | 音频时长,单位秒 |
| engineExt | Object | 引擎返回的扩展信息 |
| engineExt.alignment | Object | 原文每个字符的时间戳 |
| engineExt.normalized_alignment | Object | 规范化文本每个字符的时间戳 |
同步语音合成 TextToSpeech
适合配音单句、短旁白、试听。单次文本不超过 2000 字符,超了返回错误,改用异步接口。官网:1041/82311。
| 参数 | 类型 | 必填 | 示例 | 说明 |
|---|---|---|---|---|
| Text | String | 是 | 您好,欢迎收听。 | 待合成文本,≤ 2000 字符 |
| VoiceId | String | 是 | 5mZxJZhSmJTjL7GoYfYI | 音色 ID。系统音色(s1_…)或克隆/设计返回的 v1_… |
| TextLang | String | 否 | zh | 文本语言,不填自动识别。可选值见语言列表 |
| Output.OutputType | String | 否 | URL | 填 URL 时返回 AudioUrl(24 小时有效)而非 base64 |
| ExtParam | String | 否 | {"engine":"tts-l1", ...} | 引擎与扩展参数(JSON 字符串),见引擎主要参数 |
异步语音合成 TextToSpeechAsync
长文本(有声书章节、整篇解说稿)走异步:下发任务拿 TaskId,再轮询结果。官网:1041/79693。
| 参数 | 类型 | 必填 | 示例 | 说明 |
|---|---|---|---|---|
| Text | String | 是 | 长文本… | 待合成文本,无 2000 字符限制 |
| VoiceId | String | 是 | v1_… | 音色 ID |
| TextLang | String | 否 | zh | 文本语言,不填自动探测 |
| ExtParam | String | 否 | {"engine":"tts-l1","synExt":{...}} | 同同步接口;另支持 transExt 做先翻译后合成 |
| Output | Object | 否 | {"OutputType":"URL"} | 输出形式 |
transExt 可以在合成前顺带翻译(做多语言版本时省一次调用):
{
"transExt": {
"transInfo": { "transDst": "en" },
"transRequirement": "引号内的内容不翻译"
}
}返回 TaskId 后用 DescribeTextToSpeechAsyncTask(官网:1041/79696)查询:
| 参数 | 类型 | 说明 |
|---|---|---|
| TaskId | String | 必填,任务 ID |
| Status | String | success / fail / processing |
| AudioUrl | String | 合成音频 URL |
| VoiceId | String | 本次使用的音色 ID |
| ExtInfo | String | 扩展信息(如 {"duration":1.00325}) |
ErrorCode 在处理中返回 100,不要当成失败。
音色克隆 CloneVoice
给一段参考音频(5 秒以上、单一说话人、无背景音乐),换回一个可复用的 VoiceId。官网:1041/82312。
| 参数 | 类型 | 必填 | 示例 | 说明 |
|---|---|---|---|---|
| AudioData | String | 二选一 | base64 | 参考音频 base64 |
| AudioUrl | String | 二选一 | https://…/voice.wav | 参考音频 URL,AudioData 为空时生效 |
| AudioLang | String | 否 | zh | 参考音频语言,默认中文 |
| VoiceProfile.Name | String | 否 | brand-narrator-01 | 音色名,便于 DescribeVoices 检索 |
| VoiceProfile.Gender / Age / Labels / Scenes | String / Array | 否 | male / middle_aged / ["磁性"] | 音色属性,查询和匹配时用 |
| Text | String | 否 | 你好,这是一段试听音频 | 试听文本,返回里给一段预览音频 |
| TextLang | String | 否 | zh | 试听文本语言 |
| Output.OutputType | String | 否 | URL | 试听音频的输出形式 |
| ExtParam | String | 否 | {"engine":"tts-l1"} | 指定引擎 |
返回 VoiceId(v1_ + 一长串加密 base64,80 字符以上)。这个值要整体保存、原样回传,不要做 URL 编码或截断 —— 它包含 /、+、= 等字符,截断后报的是"音色不存在",很难定位。
克隆与设计音色的数量上限默认 100 个,超限用 DeleteVoice 清理或申请扩容;音色属性写错了用 UpdateVoice 改,不必重新克隆。
音色设计 DesignVoiceAsync
不提供音频,只给文字描述,让模型生成一个新音色。适合"我还没有合适的配音员"的早期阶段。官网:1041/79694。
| 参数 | 类型 | 必填 | 示例 | 说明 |
|---|---|---|---|---|
| Prompt | String | 是 | 电影解说男声,抑扬顿挫,低沉富有磁性 | 音色描述,越具体越稳 |
| VoiceProfile | Object | 否 | {"Name":"commentary-male"} | 音色属性 |
| Text | String | 否 | 在一个风雨交加的夜晚… | 试听文本,≤ 500 字符;填了才返回试听音频 |
| ExtParam | String | 否 | {"promptEnhance":true} | promptEnhance 自动扩写描述;同样可指定 engine |
返回 TaskId,用 DescribeDesignTask(官网:1041/79598)查结果:
| 参数 | 类型 | 说明 |
|---|---|---|
| TaskId | String | 必填 |
| Status | String | success / fail / processing |
| VoiceId | String | 生成的音色 ID(可能为 null) |
| AudioUrl | String | 试听音频 URL(请求里带了 Text 才有) |
| ExtInfo | String | 扩展信息(如 {"name":"甜美女声"}) |
同样的 Prompt 不保证生成同样的音色 —— 要可复现就把拿到的 VoiceId 存下来,别再重新设计。
查询可用音色 DescribeVoices
按类型、性别、年龄、语言、标签筛选音色。官网:1041/79695。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| VoiceType | String | 否 | system / clone / design / all(默认) |
| VoiceId | String | 否 | 按 ID 精确查 |
| VoiceName | String | 否 | 音色名,模糊匹配 |
| Gender / Age | String | 否 | male/female/unknown;child/teenager/youth/middle_aged/senior/unknown |
| Languages.N | Array of String | 否 | 如 ["zh"] |
| Labels.N / Scenes.N | Array of String | 否 | 如 ["知性"] / ["解说"] |
| PageNum / PageSize | Integer | 否 | 分页,不填返回全部 |
| ExtParam | String | 否 | 查 ElevenLabs 音色时填 {"engine":"tts-l1"} |
返回 TotalCount 与 Voices[],每个元素含 VoiceId / Name / Category / Gender / Age / Languages / Labels / Scenes / Description / AudioUrl(试听)。
不加 engine 时查到的是 MPS 全量音色池(含非 ElevenLabs 引擎),把 VoiceId 拿去 TTS-L1 合成可能不认 —— 排查"音色无效"时先确认这一点。
ElevenLabs 自带的官方音色库见 elevenlabs.io/app/default-voices,可以按风格挑好再来核对 ID。
调用示例
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(endpoint="mps.tencentcloudapi.com")
client = mps_client.MpsClient(cred, "ap-guangzhou", ClientProfile(http_profile=http_profile))
# ① 同步合成:tts-l1 + v3 模型 + 0.9 倍语速 + 字符时间戳
req = models.TextToSpeechRequest()
req.from_json_string(json.dumps({
"Text": "您好,欢迎使用 TTS-L1 语音合成。",
"TextLang": "zh",
"VoiceId": "5mZxJZhSmJTjL7GoYfYI",
"Output": {"OutputType": "URL"},
"ExtParam": json.dumps({
"engine": "tts-l1",
"synExt": {
"model": "tts-l1-v3",
"format": "mp3",
"speed": 0.9,
"engineCustom": {
"voice_settings": {"stability": 0.5, "use_speaker_boost": True},
"with_timestamps": True
}
}
})
}))
print(client.TextToSpeech(req).to_json_string())# ② 音色复刻:拿一段参考音频换 VoiceId(同步)
req = models.CloneVoiceRequest()
req.from_json_string(json.dumps({
"AudioUrl": "https://example.com/reference-voice.wav",
"AudioLang": "zh",
"VoiceProfile": {"Name": "brand-narrator-01", "Gender": "male"},
"Text": "你好,这是一段试听音频",
"ExtParam": json.dumps({"engine": "tts-l1"})
}))
resp = client.CloneVoice(req)
print(resp.VoiceId) # v1_... 整体保存,后续 TTS 直接复用# ③ 长文本:下任务后轮询
req = models.TextToSpeechAsyncRequest()
req.from_json_string(json.dumps({
"Text": "<长文本>",
"TextLang": "zh",
"VoiceId": "<VoiceId>",
"ExtParam": json.dumps({"engine": "tts-l1", "synExt": {"model": "tts-l1-turbo_v2_5"}})
}))
task_id = client.TextToSpeechAsync(req).TaskId
q = models.DescribeTextToSpeechAsyncTaskRequest()
q.from_json_string(json.dumps({"TaskId": task_id}))
print(client.DescribeTextToSpeechAsyncTask(q).to_json_string()) # Status / AudioUrl字符级时间戳与字幕对齐
with_timestamps: true 会额外返回 engineExt.alignment 与 engineExt.normalized_alignment,用于做逐字字幕、配音与画面卡点。
alignment:对应你传入的原文的每个字符;normalized_alignment:对应实际读出的规范化文本(数字、缩写、符号会被展开成读法),与原文不是逐字一键对应。
典型结构是 ElevenLabs 原生的三等长数组(characters / character_start_times_seconds / character_end_times_seconds):
{
"engineExt": {
"alignment": {
"characters": ["您", "好"],
"character_start_times_seconds": [0.0, 0.18],
"character_end_times_seconds": [0.18, 0.42]
}
}
}先打一次日志再写解析
这个结构是 ElevenLabs 原生的字段布局,《TTS-L1 引擎接入指引》里只写了"每个字符的时间戳信息"、没有展开字段名。做逐字字幕前先打一次完整返回体确认键名,别直接按上面的示例写死解析 —— 引擎版本升级时字段可能增减。
实操建议:
| 需求 | 做法 |
|---|---|
| 只要整句时间轴,自己按标点切句 | 不用开 with_timestamps,用 ExtInfo.duration + 估算语速即可 |
| 逐字高亮字幕(卡拉 OK 式) | 开 with_timestamps,用 normalized_alignment 对音频、alignment 对原文 |
| 配音与画面对齐(口型/卡点) | 先用 duration 校验总时长,超了调 synExt.speed(0.7~1.2)或删减文本 |
| 多段拼成一条完整音轨 | 分段合成时带 previous_text / next_text,拼接处按 duration 累加时间轴偏移 |
限制与注意事项
- 同步接口单次
2000字符上限;长文一律走TextToSpeechAsync。 AudioUrl有效期24 小时,要长期保存必须落自己的 COS,不要存 URL 当资产。- 克隆/设计音色数量上限默认
100个。 - 单接口
20 次/秒;批量合成请自己做并发控制与重试(ErrorCode=100是处理中,不是失败)。 TextLang不填时是自动识别。中英混排文案建议显式指定主语言,否则识别偏差会让整段换一个读法。- 引擎参数拼错不会报错:
ExtParam里写了引擎不认识的键,多数情况被静默忽略,返回一段"能听但不对"的音频。改参数后先合成一句话试听,别直接跑批量。
TextLang 语言列表
MPS 侧官方支持(40 个,注意匈牙利语写作 hun、菲律宾语写作 fil,不是 ISO 的 hu/tl,按字符串原样传):
zh 中文 / en 英语 / ja 日语 / de 德语 / fr 法语 / ko 韩语 / ru 俄语 / uk 乌克兰语 / pt 葡萄牙语 / it 意大利语 / es 西班牙语 / id 印尼语 / nl 荷兰语 / tr 土耳其语 / fil 菲律宾语 / ms 马来语 / el 希腊语 / fi 芬兰语 / hr 克罗地亚语 / sk 斯洛伐克语 / pl 波兰语 / sv 瑞典语 / hi 印地语 / bg 保加利亚语 / ro 罗马尼亚语 / ar 阿拉伯语 / cs 捷克语 / da 丹麦语 / ta 泰米尔语 / hun 匈牙利语 / vi 越南语 / no 挪威语 / yue 粤语 / th 泰语 / he 希伯来语 / ca 加泰罗尼亚语 / nn 新挪威语 / af 南非荷兰语 / fa 波斯语 / sl 斯洛文尼亚语
具体某个模型覆盖哪些语言,以该模型在 ElevenLabs 官方的语言支持为准 —— multilingual_v2 覆盖面最广,turbo / flash 系列对部分小语种支持较弱。
相关文档
站内:
| 文档 | 内容 |
|---|---|
| MPS 七大 TTS 引擎横向对比 | 七个外部引擎的能力、参数与选型对比 |
| TTS-Gemini | 同一套接口的 Google Gemini-TTS 引擎(tts-gg),用 prompt 控制风格,不支持克隆 |
| TTS-MiniMax | 同一套接口的 MiniMax 引擎(minimax),支持克隆与音色设计 |
| TTS-Seed | 同一套接口的 TTS-Seed 引擎(tts-s),24 种情绪枚举 |
| TTS-Fishaudio | 同一套接口的 Fish Audio 引擎(tts-f),内联情绪标签与零样本克隆 |
| TTS-Index | 同一套接口的 IndexTTS 引擎(index-tts),VoiceId 直填参考音频 URL,8 维情感向量 |
| TTS-Seedaudio | 同一套接口的 Seed Audio 引擎(tts-sa),唯一支持图片参考生成,字级时间戳 |
| AI Dubbing | 整段视频换语言、说话人替换(ProcessMedia + 配音模板) |
| MPS API Reference | TC3 签名、公共参数、错误码 |
| API Key 环境变量 | SecretId / SecretKey 的配置方式 |
官网接口地址(腾讯云国际站 · Media AI – Dubbing APIs):各接口链接与作用见文首接口与官网文档;数据结构(VoiceProfile、VoiceInfo、VoiceUpdateFields、SyncDubbingOutputOption)见 Data Types,公共参数见 Common Params,签名见 Signature v3,错误码见 Error Codes。
ElevenLabs 官网:Text to Speech API(engineCustom 字段定义)· Models · Default Voices。