说明:此接口为 API 2.0 版本,在参数风格、错误码等方面有区别于 API 3.0 版本,请知悉。
本接口服务采用 websocket 协议,将请求文本合成为音频,同步返回合成音频数据及相关文本信息,达到“边合成边播放”的效果。
在使用该接口前,需要 开通语音合成服务,并进入 API 密钥管理页面 新建密钥,生成 AppID、SecretID 和 SecretKey,用于 API 调用时生成签名,签名将用来进行接口鉴权。
接口要求
集成实时语音合成 API 时,需按照以下要求。
内容 | 说明 |
---|---|
音色种类 | 支持中文普通话、英语、方言的合成,音色 ID 详见 音色列表页。可通过接口参数 VoiceType 设置对应音色 ID |
支持场景 | 通用、客服、情感、阅读、新闻等,详见 音色列表页 |
音频属性 | 采样率:16000Hz或8000Hz 采样精度:16bits 声道:单声道(mono) |
音频格式 | pcm、mp3、opus |
请求协议 | wss 协议 |
请求地址 | wss://tts.cloud.tencent.com/stream_ws?{请求参数} |
接口鉴权 | 签名鉴权机制,详见 签名生成 |
响应格式 | 音频信息通过 binary 类型帧,返回原始二进制数据; 文本信息通过 text 类型帧,返回 JSON 格式数据(如状态码、时间戳等) |
并发限制 | 默认单账号限制并发连接数为20路,如您有提高并发限制的需求,请联系商务经理咨询或 购买并发。 |
接口调用流程
接口调用流程分为两个阶段:握手阶段和合成阶段。两阶段后台均会返回 text message,内容为 json 序列化字符串,以下是格式说明:
字段名 | 类型 | 描述 |
---|---|---|
code | Integer | 状态码,0代表正常,非0值表示发生错误 |
message | String | 错误说明,发生错误时显示这个错误发生的具体原因,随着业务发展或体验优化,此文本可能会经常保持变更或更新 |
session_id | String | 音频流唯一 id,由客户端在握手阶段生成并赋值在调用参数中 |
request_id | String | 音频流唯一 id,由服务端在握手阶段自动生成 |
message_id | String | 本 message 唯一 id |
result | Result | 最新语音合成文本结果 |
final | Integer | 该字段返回1时表示文本全部合成结束,客户端收到后需主动关闭 websocket 连接 |
其中合成结果 Result 结构体格式为:
字段名 | 类型 | 描述 |
---|---|---|
subtitles | Subtitle Array | 当前一段话的词列表,Subtitle 结构体格式为: Text: String 类型,该字的内容。 BeginTime: Integer 类型,该字在整个音频流中的起始时间。 EndTime: Integer 类型,该字在整个音频流中的结束时间。 BeginIndex: Integer 类型,该字在整个文本中的开始位置,从0开始。 EndIndex: Integer 类型,该字在整个文本中的结束位置,从0开始。 Phoneme: String 类型,该字的音素(注意:此字段可能返回 null,表示取不到有效值)。 |
握手阶段
请求格式
握手阶段,客户端主动发起 websocket 连接请求,请求 URL 格式为:
wss://tts.cloud.tencent.com/stream_ws?{请求参数}
其中<appid>需替换为腾讯云注册账号的 AppID,可通过 API 密钥管理页面 获取,{请求参数}格式为
key1=value2&key2=value2...(key 和 value 都需要进行 urlencode)
参数说明:
参数名称 | 必填 | 类型 | 描述 |
---|---|---|---|
Action | 是 | String | 调用接口名,取值为:TextToStreamAudioWS |
AppId | 是 | Integer | 账号 AppId(请确保该字段数据类型为整型 int) |
SecretId | 是 | String | 腾讯云注册账号的密钥 SecretId,可通过 API 密钥管理页面 获取 |
Timestamp | 是 | Integer | 当前 UNIX 时间戳,可记录发起 API 请求的时间。例如1529223702,如果与当前时间相差过大,会引起签名过期错误 |
Expired | 是 | Integer | 签名的有效期,是一个符合 UNIX Epoch 时间戳规范的数值,单位为秒;Expired 必须大于 Timestamp 且 Expired-Timestamp 小于90天 |
SessionId | 是 | String | 语音合成全局唯一标识,一个 websocket 连接对应一个,用户自己生成(推荐使用 uuid),最长128位。 |
Text | 是 | String | 合成语音的源文本,按UTF-8编码统一计算。中文最大支持 600 个汉字(全角标点符号算一个汉字);英文最大支持 1800 个字母(半角标点符号算一个字母)。 |
VoiceType | 否 | Integer | 音色 ID,包括标准音色与精品音色,精品音色拟真度更高,价格不同于标准音色,请参见 购买指南。完整的音色 ID 列表请参见 音色列表。 |
Volume | 否 | Float | 音量大小,范围[-10,10],对应音量大小。默认为0,代表正常音量,值越大音量越高。 |
Speed | 否 | Float | 语速,范围:[-2,6],分别对应不同语速: -2: 代表0.6倍 -1: 代表0.8倍 0: 代表1.0倍(默认) 1: 代表1.2倍 2: 代表1.5倍 6: 代表2.5倍 如果需要更细化的语速,可以保留小数点后 2 位,例如0.5/1.25/2.81等。 参数值与实际语速转换,可参考 代码示例 |
SampleRate | 否 | Integer | 音频采样率: |
Codec | 否 | String | 返回音频格式: opus: 返回多段含 opus 压缩分片音频(默认) pcm: 返回二进制 pcm 音频 mp3: 返回二进制 mp3 音频 |
EnableSubtitle | 否 | Boolean | 是否开启时间戳功能,默认为false。 |
EmotionCategory | 否 | String | 控制合成音频的情感,仅支持多情感音色使用。取值: neutral(中性)、sad(悲伤)、happy(高兴)、angry(生气)、fear(恐惧)、news(新闻)、story(故事)、radio(广播)、poetry(诗歌)、call(客服)、sajiao(撒娇)、disgusted(厌恶)、amaze(震惊)、peaceful(平静)、exciting(兴奋)、aojiao(傲娇)、jieshuo(解说) 示例值:neutral |
EmotionIntensity | 否 | Integer | 控制合成音频情感程度,取值范围为 [50,200],默认为 100;只有 EmotionCategory 不为空时生效。 |
SegmentRate | 否 | Integer | 断句敏感阈值,取值范围:[0,1,2],默认值:0 该值越大越不容易断句,模型会更倾向于仅按照标点符号断句。此参数建议不要随意调整,可能会影响合成效果 |
Signature | 是 | String | 接口签名参数 |
- 对除 Signature 之外的所有参数按字典序进行排序,拼接后得到请求参数为
再拼接请求方法、域名地址,得到签名原文。签名原文格式为Action=TextToStreamAudioWS&AppId=130046****&Codec=pcm&EnableSubtitle=True&Expired=1688697305&SampleRate=16000&SecretId=*****XcaKs2w4vZw5zTCrHRM7dOwre9*****&SessionId=b78ae3ba-1ba5-11ee-a106-768645a5c72a&Speed=0&Text=欢迎使用腾讯云实时语音合成&Timestamp=1688610905&VoiceType=101001&Volume=0
最终,得到的签名原文为:请求方法(GET) + 域名地址(tts.cloud.tencent.com/stream_ws) + 请求参数(?Action=TextToStreamAudioWS&其他参数...)
GETtts.cloud.tencent.com/stream_ws?Action=TextToStreamAudioWS&AppId=130046****&Codec=pcm&EnableSubtitle=True&Expired=1688697305&SampleRate=16000&SecretId=*****XcaKs2w4vZw5zTCrHRM7dOwre9*****&SessionId=b78ae3ba-1ba5-11ee-a106-768645a5c72a&Speed=0&Text=欢迎使用腾讯云实时语音合成&Timestamp=1688610905&VoiceType=101001&Volume=0
- 对签名原文使用 SecretKey 进行 HmacSha1 加密,之后再进行 base64 编码。例如对上一步的签名原文,
SecretKey=*****SkqpeHgqmSz*****
,使用 HmacSha1 算法进行加密并做 base64 编码处理:
得到 Signature 签名值为:Base64Encode(HmacSha1("GETtts.cloud.tencent.com/stream_ws?Action=TextToStreamAudioWS&AppId=130046****&Codec=pcm&EnableSubtitle=True&Expired=1688697305&SampleRate=16000&SecretId=*****XcaKs2w4vZw5zTCrHRM7dOwre9*****&SessionId=b78ae3ba-1ba5-11ee-a106-768645a5c72a&Speed=0&Text=欢迎使用腾讯云实时语音合成&Timestamp=1688610905&VoiceType=101001&Volume=0", "*****SkqpeHgqmSz*****"))
4Lv+k6y6v5VRT/iBFPU+Gyfeiy0=
- 将 Signature 值进行 urlencode(必须进行 URL 编码,否则将导致鉴权失败偶现 )后拼接得到 URL 为:
wss://tts.cloud.tencent.com/stream_ws?Action=TextToStreamAudioWS&AppId=130046****&Codec=pcm&EnableSubtitle=True&Expired=1688697305&SampleRate=16000&SecretId=*****XcaKs2w4vZw5zTCrHRM7dOwre9*****&SessionId=b78ae3ba-1ba5-11ee-a106-768645a5c72a&Speed=0&Text=欢迎使用腾讯云实时语音合成&Timestamp=1688610905&VoiceType=101001&Volume=0&Signature=4Lv%2Bk6y6v5VRT/iBFPU%2BGyfeiy0%3D
- 将 Text 值进行 urlencode编码,替换原始文本值
得到最终的请求 URL 为:Text=欢迎使用腾讯云实时语音合成 替换为 Text=%E6%AC%A2%E8%BF%8E%E4%BD%BF%E7%94%A8%E8%85%BE%E8%AE%AF%E4%BA%91%E5%AE%9E%E6%97%B6%E8%AF%AD%E9%9F%B3%E5%90%88%E6%88%90
wss://tts.cloud.tencent.com/stream_ws?Action=TextToStreamAudioWS&AppId=130046****&Codec=pcm&EnableSubtitle=True&Expired=1688697305&SampleRate=16000&SecretId=*****XcaKs2w4vZw5zTCrHRM7dOwre9*****&SessionId=b78ae3ba-1ba5-11ee-a106-768645a5c72a&Speed=0&Text=%E6%AC%A2%E8%BF%8E%E4%BD%BF%E7%94%A8%E8%85%BE%E8%AE%AF%E4%BA%91%E5%AE%9E%E6%97%B6%E8%AF%AD%E9%9F%B3%E5%90%88%E6%88%90&Timestamp=1688610905&VoiceType=101001&Volume=0&Signature=4Lv%2Bk6y6v5VRT/iBFPU%2BGyfeiy0%3D
请求响应
客户端发起连接请求后,后台建立连接并进行签名校验,校验成功则返回 code 值为 0 的确认消息表示握手成功;如果校验失败,后台返回 code 为非 0 值的消息并断开连接。
{"code":0,"message":"success","session_id":"e042008c-1019-11ee-8b49-6c92bf65e6fe","request_id":"b028dfe6-d7af-4d25-b61d-dcae685aa81f","message_id":"f81c0771-5606-478e-9560-555a5717ea25","final":0,"result":{"subtitles":null}}
合成阶段
握手成功之后,进入合成阶段,客户端接收合成的音频二进制数据、文本数据(如时间戳)。
接收消息
客户端需要同步接收后台返回的二进制音频数据与文本数据。文本数据示例如下:
{"code":0,"message":"success","session_id":"659f1260-101a-11ee-959d-6c92bf65e6fe","request_id":"20ebf801-53ee-4a58-96ab-c63e0f16044a","message_id":"8d4a2f2b-3b15-445c-933b-74b6b44cd882","final":0,"result":{"subtitles":[{"Text":"欢","BeginTime":250,"EndTime":570,"BeginIndex":0,"EndIndex":1,"Phoneme":"huan1"},{"Text":"迎","BeginTime":570,"EndTime":770,"BeginIndex":1,"EndIndex":2,"Phoneme":"ying2"},{"Text":"使","BeginTime":770,"EndTime":1020,"BeginIndex":2,"EndIndex":3,"Phoneme":"shi3"},{"Text":"用","BeginTime":1020,"EndTime":1270,"BeginIndex":3,"EndIndex":4,"Phoneme":"yong4"}]}}
后台合成完所有音频数据之后,最终返回 final 值为1的消息,客户端收到后,需主动断开 websocket 连接。{"code":0,"message":"success","session_id":"dbb8417e-101a-11ee-840e-6c92bf65e6fe","request_id":"99207183-3bda-42de-a1f4-6d8838122ad3","message_id":"d56a3fed-0dd6-4dc6-b434-416ae1b69f0f","final":1,"result":{"subtitles":null}}
合成过程中如果出现错误,后台返回 code 为非 0 值的消息并断开连接。{"code":10001,"message":"参数不合法(Please check your parameter VoiceType)","session_id":"b6b10dc0-101a-11ee-9e72-6c92bf65e6fe","request_id":"a2edbe4f-c12f-48e6-8810-fda7a0992f79","message_id":"da63be2f-d44e-4f3b-a2d7-0b19a3748d23","final":0,"result":{"subtitles":null}}
调用流程示意图
开发者资源
SDK
- Tencent Cloud Speech SDK for Java
- Tencent Cloud Speech SDK for Python
- Tencent Cloud Speech SDK for C++
- Tencent Cloud Speech SDK for Go
SDK 调用示例
错误码
数值 | 说明 |
---|---|
10001 | 参数不合法,具体详情参考 message 字段 |
10002 | 账号当前调用并发超限败 |
10003 | 鉴权失败 |
10004 | 客户端数据上传超时 |
10005 | 客户端连接断开 |
20000 | 后台错误 |
20001 | 后台服务器合成失败 |
20002 | 后台引擎合成失败 |
20003 | 后台引擎合成超时 |