接口描述
本接口服务采用 WebSocket 协议,在实时语音识别的基础上,新增加声纹聚类能力,可以实时对说话人角色进行分离,达到“边说边出文字边识别角色”的效果。在使用该接口前,需要 开通语音识别服务,并进入 API 密钥管理页面 新建密钥,生成 AppID、SecretId 和 SecretKey,用于 API 调用时生成签名,签名将用来进行接口鉴权。
接口要求
集成实时语音识别 API 时,需按照以下要求。
内容 | 说明 |
语言种类 | 支持中文、英语、粤语、四川、陕西、河南、上海、湖南、湖北和安徽方言。可通过接口参数 engine_model_type 设置对应语言类型。 |
音频属性 | 采样率:16000Hz 或 8000Hz 采样精度:16bits 声道:单声道(mono) |
音频格式 | pcm、wav、opus、speex、silk、mp3、m4a、aac |
请求协议 | wss 协议 |
请求地址 | wss://asr.cloud.tencent.com/asr/v2/<appid>?{请求参数} |
接口鉴权 | |
响应格式 | 统一采用 JSON 格式。 |
数据发送 | 建议200ms发送200ms时长(即1:1实时率)的数据包,对应 PCM 大小为:8k 采样率3200字节,16k采样率6400字节。 音频发送速率过快超过1:1实时率或者音频数据包之间发送间隔超过6秒,可能导致引擎出错,后台将返回错误并主动断开连接。 |
并发限制 | 单账号免费50路并发,如您有提高并发限制的需求,请联系腾讯云服务支持。 |
接口调用流程
接口调用流程分为两个阶段:握手阶段和识别阶段。两阶段后台均返回 text message,内容为 JSON 序列化字符串,以下是格式说明:
字段名 | 类型 | 描述 |
code | Integer | 状态码,0代表正常,非0值表示发生错误。 |
message | String | 错误说明,发生错误时显示这个错误发生的具体原因,随着业务发展或体验优化,此文本可能会经常保持变更或更新。 |
voice_id | String | 音频流全局唯一标识,一个 WebSocket 连接对应一个,用户自己生成(推荐使用 UUID),最长128位。 注意:每次建立 WebSocket 连接都必须重新生成 voice_id,任何情况下中断了识别或者 WebSocket 连接(如连接失败、正常结束、识别返回错误码等),voice_id 作废,重新发起识别必须使用新的 voice_id。 |
message_id | String | 本 message 唯一 ID。 |
sentences | SpeakerSentences | 最新带说话人信息的语音识别结果。 |
final | Integer | 该字段返回1时表示音频流全部识别结束。 |
其中识别结果 sentences 结构体格式为:
字段名 | 类型 | 描述 |
sentence | string | 当前句子的文本内容。 |
sentence_type | Int | 当前句子的状态,0为不确定,1为确定。 |
sentence_id | Int | 当前句子的 ID,从0开始,每产生一个稳态的句子,会进行自增。 |
speaker_id | Int | 代表当前句的说话人信息,起始会从-1开始展示,表示未产生准确的说话人信息,产生准确说话人信息后,该字段将替换为一个正数来指代具体的说话人角色信息,说话人角色id,有效取值范围 0 - 9, 最多分离10个说话人。 |
start_time | uint | 当前一段话结果在整个音频流中的起始时间。 |
end_time | uint | 当前一段话结果在整个音频流中的结束时间。 |
握手阶段
请求格式
握手阶段,客户端主动发起 WebSocket 连接请求,请求 URL 格式为:
wss://asr.cloud.tencent.com/asr/v2/<appid>?{请求参数}
key1=value2&key2=value2...
参数说明:
参数名称 | 必填 | 类型 | 描述 |
secretid | 是 | String | 示例值:*****Qq1zhZMN8dv0****** |
timestamp | 是 | Integer | 当前 UNIX 时间戳,单位为秒。如果与当前时间相差过大,会引起签名过期错误。 示例值:1745932688 |
expired | 是 | Integer | 签名的有效期截止时间 UNIX 时间戳,单位为秒。expired 必须大于 timestamp 且 expired - timestamp 小于90天。 示例值:1746019088 |
nonce | 是 | Integer | 随机正整数。用户需自行生成,最长10位。 示例值:8743357 |
engine_model_type | 是 | String | 支持实时话者分离的引擎: 16k_zh_en_speaker:中英粤+7种方言大模型引擎【大模型版】。当前模型同时支持中文、英语、粤语、四川、陕西、河南、上海、湖南、湖北和安徽方言识别,模型参数量极大,语言模型性能增强,针对噪声大、回音大、人声小、人声远等低质量音频的识别准确率极大提升。 示例值:16k_zh_en_speaker |
voice_id | 是 | String | 音频流全局唯一标识,一个 WebSocket 连接对应一个,用户自己生成(推荐使用 UUID),最长128位。 注意:每次建立 WebSocket 连接都必须重新生成 voice_id,任何情况下中断了识别或者 WebSocket 连接(如连接失败、正常结束、识别返回错误码等),voice_id 作废,重新发起识别必须使用新的 voice_id 示例值:TBgVFCsxdn3i2DGt |
enable_speaker_context | 否 | Int | 是否开启断点续传能力;0:关闭,1:开启。 若开启断点续传能力,会返回唯一声纹 ID(24h 有效),用于下次任务断点续传。 |
speaker_context_id | 否 | String | 传入声纹 ID 后,本次实时话者分离说话人 ID 会与上次的实时话者分离任务保持一致。 |
voice_format | 否 | Int | 语音编码方式,可选,默认值为4。1:pcm;4:speex(sp);6:silk;8:mp3;10:opus(opus 格式音频流封装说明);12:wav;14:m4a(每个分片须是一个完整的 m4a 音频);16:aac 示例值:1 |
needvad | 否 | Integer | 0:关闭 vad,1:开启 vad,默认为0。 为保证识别效果,如果语音分片长度超过60秒,会强制在 60s 断一次,建议客户音频超过 60s 时,开启 vad(人声检测切分功能),提升切分效果。 示例值:1 |
hotword_id | 否 | String | 热词表 id。如不设置该参数,自动生效默认热词表;如果设置了该参数,那么将生效对应的热词表。 示例值:da3f5f5555cf11eda6da525400aec391 |
customization_id | 否 | String | 自学习模型 id。如设置了该参数,将生效对应的自学习模型。 示例值:39bc8e96504511edbd76446a2eb5fd98 |
filter_dirty | 否 | Integer | 是否过滤脏词(目前支持中文普通话引擎)。默认为0。0:不过滤脏词;1:过滤脏词;2:将脏词替换为“ * ” 示例值:0 |
filter_modal | 否 | Integer | 是否过滤语气词(目前支持中文普通话引擎)。默认为0。0:不过滤语气词;1:部分过滤;2:严格过滤。 示例值:0 |
filter_empty_result | 否 | Integer | 是否回调识别空结果,默认为1。0:回调空结果;1:不回调空结果。 注意:如果需要 slice_type=0 和 slice_type=2 配对回调,需要设置 filter_empty_result=0。一般在外呼场景需要配对返回,通过 slice_type=0 来判断是否有人声出现。 示例值:1 |
convert_num_mode | 否 | Integer | 是否进行阿拉伯数字智能转换(目前支持中文普通话引擎)。0:不转换,直接输出中文数字,1:根据场景智能转换为阿拉伯数字,3: 打开数学相关数字转换。默认值为1 示例值:1 |
noise_threshold | 否 | Float | 噪音参数阈值,默认为0,取值范围:[-1,1],对于一些音频片段,取值越大,判定为噪音情况越大。取值越小,判定为人声情况越大。 慎用:可能影响识别效果 示例值:0 |
signature | 是 | String | 接口签名参数 示例值:*****g1JfeBi%2FYnTjyjekxfDA%3D |
hotword_list | 否 | String | 临时热词表:该参数用于提升识别准确率。 单个热词限制:"热词|权重",单个热词不超过30个字符(最多10个汉字),权重[1-11]或者100,如:“腾讯云|5” 或 “ASR|11”。 临时热词表限制:多个热词用英文逗号分割,最多支持128个热词,如:“腾讯云|10,语音识别|5,ASR|11”。 参数 hotword_id(热词表) 与 hotword_list(临时热词表) 区别: hotword_id:热词表。需要先在控制台或接口创建热词表,获得对应hotword_id传入参数来使用热词功能。 hotword_list:临时热词表。每次请求时直接传入临时热词表来使用热词功能,云端不保留临时热词表。适用于有极大量热词需求的用户。 注意: 如果同时传入了 hotword_id 和 hotword_list,只有 hotword_list 生效。 热词权重设置为11时,当前热词将升级为超级热词,建议仅将重要且必须生效的热词设置到11,设置过多权重为11的热词将影响整体字准率。 热词权重设置为100时,当前热词开启热词增强同音替换功能(仅支持 8k_zh,16k_zh),举例:热词配置“蜜制|100”时,与“蜜制”同拼音(mizhi)的“秘制”的识别结果会被强制替换成“蜜制”。因此建议客户根据自己的实际情况开启该功能。建议仅将重要且必须生效的热词设置到100,设置过多权重为100的热词将影响整体字准率。 热词不能包含空格,如:ASR 腾讯云 示例值:语音助理|10 |
input_sample_rate | 否 | Integer | 支持 PCM 格式的 8k 音频在与引擎采样率不匹配的情况下升采样到 16k 后识别,能有效提升识别准确率。仅支持:8000。如:传入 8000 ,则 PCM 音频采样率为8k,当引擎选用16k_zh, 那么该 8k 采样率的 PCM 音频可以在 16k_zh 引擎下正常识别。 注意:此参数仅适用于 PCM 格式音频,不传入值将维持默认状态,即默认调用的引擎采样率等于 PCM 音频采样率。 示例值:8000 |
replace_text_id | 否 | String | 注意: 本功能配置完成后,预计在10分钟后生效。 |
signature 签名生成
1. 对除 signature 之外的所有参数按字典序进行排序,拼接请求 URL (不包含协议部分:wss://)作为签名原文,这里以
appid=125922***,secretid=*****Qq1zhZMN8dv0****** 为例拼接签名原文,则拼接的签名原文为:asr.cloud.tencent.com/asr/v2/125922***?engine_model_type=16k_zh&expired=1673494772&needvad=1&nonce=1673408372&secretid=*****Qq1zhZMN8dv0******×tamp=1673408372&voice_format=1&voice_id=c64385ee-3e5c-4fc5-bbfd-7c71addb35b0
2. 对签名原文使用 SecretKey 进行 HMAC-SHA1 加密,之后再进行 base64 编码。例如对上一步的签名原文,
secretkey=*****SkqpeHgqmSz*****,使用 HMAC-SHA1 算法进行加密并做 base64 编码处理:Base64Encode(HmacSha1("asr.cloud.tencent.com/asr/v2/125922***?engine_model_type=16k_zh&expired=1673494772&needvad=1&nonce=1673408372&secretid=*****Qq1zhZMN8dv0******×tamp=1673408372&voice_format=1&voice_id=c64385ee-3e5c-4fc5-bbfd-7c71addb35b0", "*****SkqpeHgqmSz*****"))
得到 signature 签名值为:
G8jDQBRg1JfeBi/YnTjyjekxfDA=
3. 将 signature 值进行 urlencode(必须进行 URL 编码,编码函数必须要支持对+、=等特殊字符的编码,否则将导致鉴权失败偶现)后拼接得到最终请求 URL 为:
wss://asr.cloud.tencent.com/asr/v2/125922****?engine_model_type=16k_zh&expired=1592380492&filter_dirty=1&filter_modal=1&filter_punc=1&needvad=1&nonce=1592294092123&secretid=A*********************************0r×tamp=1592294092&voice_format=1&voice_id=c64385ee-3e5c-4fc5-bbfd-7c71addb35b0&signature=G8jDQBRg1JfeBi%2FYnTjyjekxfDA%3D
Opus 音频流封装说明
压缩 FrameSize 固定640,即一次压缩640 short,否则解压会失败。传到服务端可以是多帧的拼接组合,每一帧需满足下面格式。
每一帧压缩数据封装如下:
OpusHead(4字节) | 帧数据长度(2字节) | Opus 一帧压缩数据 |
Opus | 长度 len | 对应 len 长的 Opus encode data |
请求响应
客户端发起连接请求后,后台建立连接并进行签名校验,校验成功则返回 code 值为0的确认消息表示握手成功;如果校验失败,后台返回 code 为非0值的消息并断开连接。
{"code":0,"message":"success","voice_id":"RnKu9FODFHK5FPpsrN"}
识别阶段
握手成功之后,进入识别阶段,客户端上传语音数据并接收识别结果消息。
上传数据
在识别过程中,客户端持续上传 binary message 到后台,内容为音频流二进制数据。建议每 40ms 发送 40ms 时长(即1:1实时率)的数据包,对应 PCM 大小为:8k 采样率640字节,16k 采样率1280字节。音频发送速率过快超过1:1实时率或者音频数据包之间发送间隔超过6秒,可能导致引擎出错,后台将返回错误并主动断开连接。
音频流上传完成之后,客户端需发送以下内容的 text message,通知后台结束识别。
{"type": "end"}
接收消息
客户端上传数据的过程中,需要同步接收后台返回的实时识别结果,结果示例:
{"code":0,"message":"success","voice_id":"RnKu9FODFHK5FPpsrN","message_id":"RnKu9FODFHK5FPpsrN_11_0","sentences":{"speaker_id:0: text:实时语音识别。sentence_id:1 start_time:1200, end_time:2850, sentence_type:1}}
后台识别完所有上传的语音数据之后,最终返回 final 值为1的消息并断开连接。
{"code":0,"message":"success","voice_id":"CzhjnqBkv8lk5pRUxhpX","message_id":"CzhjnqBkv8lk5pRUxhpX_241","final":1}
识别过程中如果出现错误,后台返回 code 为非0值的消息并断开连接。
{"code":4008,"message":"后台识别服务器音频分片等待超时","voice_id":"CzhjnqBkv8lk5pRUxhpX","message_id":"CzhjnqBkv8lk5pRUxhpX_241"}
开发者资源
SDK
SDK 调用示例
错误码
数值 | 说明 |
4000 | 音频数据发送过多,请1秒内最多发送3秒音频数据。 注意:实时识别的效果是“边说边出文字”,1秒内发送的音频数据总时长应为1秒。 |
4001 | 参数不合法,具体详情参考 message。 |
4002 | 鉴权失败。 |
4003 | AppID 服务未开通,请在控制台开通服务。 |
4004 | 资源包耗尽,请开通后付费或者购买资源包。 |
4005 | 账户欠费停止服务,请及时充值。 |
4006 | 账号当前调用并发超限。 |
4007 | 音频解码失败,请检查上传音频数据格式与调用参数一致。 |
4008 | 客户端超过15秒未发送音频数据。 |
4009 | 客户端连接断开。 |
4010 | 客户端上传未知文本消息。 |
5000 | 因机器负载过高、网络抖动等导致失败,请重新发起新识别。 注意:该问题通常为偶发,少量出现可忽略,发起新识别即可。 |
5001 | 因机器负载过高、网络抖动等导致失败,请重新发起新识别。 注意:该问题通常为偶发,少量出现可忽略,发起新识别即可。 |
5002 | 因机器负载过高、网络抖动等导致失败,请重新发起新识别。 注意:该问题通常为偶发,少量出现可忽略,发起新识别即可。 |
6001 |