跳到内容

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-l11041/82311
TextToSpeechAsync长文本转语音,返回 TaskId;可先翻译再合成异步✅ engine: tts-l11041/79693
DescribeTextToSpeechAsyncTask查询异步合成结果(Status / AudioUrl)同步跟随任务1041/79696
CloneVoice用一段参考音频克隆音色,返回可复用的 VoiceId同步✅ engine: tts-l11041/82312
DesignVoiceAsync用文字描述设计新音色,返回 TaskId异步✅ engine: tts-l11041/79694
DescribeDesignTask查询音色设计结果(VoiceId / 试听音频)同步跟随任务1041/79598
DescribeVoices按类型、性别、年龄、语言、标签筛选可用音色同步✅ 查 ElevenLabs 音色需带 engine1041/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。

text
TextToSpeech / TextToSpeechAsync / CloneVoice / DesignVoiceAsync / DescribeVoices
        │
        ├─ ExtParam 不带 engine ─────────► MPS 默认引擎
        │
        └─ ExtParam.engine = "tts-l1" ──► ElevenLabs
                 │
                 ├─ synExt.*               MPS 抽象过的参数(model / format / speed / sampleRate …)
                 └─ synExt.engineCustom.*  原样透传给 ElevenLabs 的原生参数

ExtParam 是 JSON 字符串(不是对象),放进请求体时要二次转义。最小写法:

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。

参数类型必填说明
engineString是固定 tts-l1
synExt.modelString否模型,默认 tts-l1-multilingual_v2。可选值见模型列表
synExt.formatString否输出格式:mp3 / wav / opus / alaw / ulaw,默认 wav
synExt.speedFloat否语速,默认 1.0 原速,支持 [0.7, 1.2]
synExt.engineCustomObject否ElevenLabs 原生参数透传容器
synExt.engineCustom.with_timestampsBool否返回字符级时间戳(见对齐)

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。常用三类:

json
{
  "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-v3v3 系列,表现力更强,适合解说、角色化
tts-l1-v4v4 系列,较新,可用性以账号权限为准
tts-l1-v4_turbov4 低延迟版,适合实时/高并发
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 ​

参数类型说明
ErrorCodeInteger0 成功
MsgString结果消息
AudioDataString音频 base64(未指定 Output.OutputType=URL 时返回)
AudioUrlString音频 URL,24 小时内有效
ExtInfoString扩展信息 JSON 字符串,见下表

ExtInfo 解析后:

字段类型说明
durationFloat音频时长,单位秒
engineExtObject引擎返回的扩展信息
engineExt.alignmentObject原文每个字符的时间戳
engineExt.normalized_alignmentObject规范化文本每个字符的时间戳

同步语音合成 TextToSpeech ​

适合配音单句、短旁白、试听。单次文本不超过 2000 字符,超了返回错误,改用异步接口。官网:1041/82311。

参数类型必填示例说明
TextString是您好,欢迎收听。待合成文本,≤ 2000 字符
VoiceIdString是5mZxJZhSmJTjL7GoYfYI音色 ID。系统音色(s1_…)或克隆/设计返回的 v1_…
TextLangString否zh文本语言,不填自动识别。可选值见语言列表
Output.OutputTypeString否URL填 URL 时返回 AudioUrl(24 小时有效)而非 base64
ExtParamString否{"engine":"tts-l1", ...}引擎与扩展参数(JSON 字符串),见引擎主要参数

异步语音合成 TextToSpeechAsync ​

长文本(有声书章节、整篇解说稿)走异步:下发任务拿 TaskId,再轮询结果。官网:1041/79693。

参数类型必填示例说明
TextString是长文本…待合成文本,无 2000 字符限制
VoiceIdString是v1_…音色 ID
TextLangString否zh文本语言,不填自动探测
ExtParamString否{"engine":"tts-l1","synExt":{...}}同同步接口;另支持 transExt 做先翻译后合成
OutputObject否{"OutputType":"URL"}输出形式

transExt 可以在合成前顺带翻译(做多语言版本时省一次调用):

json
{
  "transExt": {
    "transInfo": { "transDst": "en" },
    "transRequirement": "引号内的内容不翻译"
  }
}

返回 TaskId 后用 DescribeTextToSpeechAsyncTask(官网:1041/79696)查询:

参数类型说明
TaskIdString必填,任务 ID
StatusStringsuccess / fail / processing
AudioUrlString合成音频 URL
VoiceIdString本次使用的音色 ID
ExtInfoString扩展信息(如 {"duration":1.00325})

ErrorCode 在处理中返回 100,不要当成失败。

音色克隆 CloneVoice ​

给一段参考音频(5 秒以上、单一说话人、无背景音乐),换回一个可复用的 VoiceId。官网:1041/82312。

参数类型必填示例说明
AudioDataString二选一base64参考音频 base64
AudioUrlString二选一https://…/voice.wav参考音频 URL,AudioData 为空时生效
AudioLangString否zh参考音频语言,默认中文
VoiceProfile.NameString否brand-narrator-01音色名,便于 DescribeVoices 检索
VoiceProfile.Gender / Age / Labels / ScenesString / Array否male / middle_aged / ["磁性"]音色属性,查询和匹配时用
TextString否你好,这是一段试听音频试听文本,返回里给一段预览音频
TextLangString否zh试听文本语言
Output.OutputTypeString否URL试听音频的输出形式
ExtParamString否{"engine":"tts-l1"}指定引擎

返回 VoiceId(v1_ + 一长串加密 base64,80 字符以上)。这个值要整体保存、原样回传,不要做 URL 编码或截断 —— 它包含 /、+、= 等字符,截断后报的是"音色不存在",很难定位。

克隆与设计音色的数量上限默认 100 个,超限用 DeleteVoice 清理或申请扩容;音色属性写错了用 UpdateVoice 改,不必重新克隆。

音色设计 DesignVoiceAsync ​

不提供音频,只给文字描述,让模型生成一个新音色。适合"我还没有合适的配音员"的早期阶段。官网:1041/79694。

参数类型必填示例说明
PromptString是电影解说男声,抑扬顿挫,低沉富有磁性音色描述,越具体越稳
VoiceProfileObject否{"Name":"commentary-male"}音色属性
TextString否在一个风雨交加的夜晚…试听文本,≤ 500 字符;填了才返回试听音频
ExtParamString否{"promptEnhance":true}promptEnhance 自动扩写描述;同样可指定 engine

返回 TaskId,用 DescribeDesignTask(官网:1041/79598)查结果:

参数类型说明
TaskIdString必填
StatusStringsuccess / fail / processing
VoiceIdString生成的音色 ID(可能为 null)
AudioUrlString试听音频 URL(请求里带了 Text 才有)
ExtInfoString扩展信息(如 {"name":"甜美女声"})

同样的 Prompt 不保证生成同样的音色 —— 要可复现就把拿到的 VoiceId 存下来,别再重新设计。

查询可用音色 DescribeVoices ​

按类型、性别、年龄、语言、标签筛选音色。官网:1041/79695。

参数类型必填说明
VoiceTypeString否system / clone / design / all(默认)
VoiceIdString否按 ID 精确查
VoiceNameString否音色名,模糊匹配
Gender / AgeString否male/female/unknown;child/teenager/youth/middle_aged/senior/unknown
Languages.NArray of String否如 ["zh"]
Labels.N / Scenes.NArray of String否如 ["知性"] / ["解说"]
PageNum / PageSizeInteger否分页,不填返回全部
ExtParamString否查 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。

调用示例 ​

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(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())
python
# ② 音色复刻:拿一段参考音频换 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 直接复用
python
# ③ 长文本:下任务后轮询
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):

json
{
  "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 ReferenceTC3 签名、公共参数、错误码
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。

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