实时说话人分离(WebSocket)

最近更新时间:2026-05-06 19:53:00

我的收藏

接口描述

本接口服务采用 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>?{请求参数}
其中 <appid> 需替换为腾讯云注册账号的 AppID,可通过 API 密钥管理页面 获取,{请求参数}格式为:
key1=value2&key2=value2...
参数说明:
参数名称
必填
类型
描述
secretid
String
腾讯云注册账号的密钥 SecretId,可通过 API 密钥管理页面 获取。
示例值:*****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
替换词汇表 ID, 适用于热词和自学习场景也无法解决的极端 case 词组,会对识别结果强制替换。具体可参考(词汇替换) ;强制替换功能可能会影响正常识别结果,请谨慎使用。

注意:
本功能配置完成后,预计在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******&timestamp=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******&timestamp=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&timestamp=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

Tencent Cloud Speech SDK for Go:GitHub,CNB
Tencent Cloud Speech SDK for Java:GitHub,CNB
Tencent Cloud Speech SDK for Python:GitHub,CNB


SDK 调用示例

错误码

数值
说明
4000
音频数据发送过多,请1秒内最多发送3秒音频数据。
注意:实时识别的效果是“边说边出文字”,1秒内发送的音频数据总时长应为1秒。
4001
参数不合法,具体详情参考 message。
4002
鉴权失败。
4003
AppID 服务未开通,请在控制台开通服务。
4004
资源包耗尽,请开通后付费或者购买资源包。
4005
账户欠费停止服务,请及时充值。
4006
账号当前调用并发超限。
4007
音频解码失败,请检查上传音频数据格式与调用参数一致。
4008
客户端超过15秒未发送音频数据。
4009
客户端连接断开。
4010
客户端上传未知文本消息。
5000
因机器负载过高、网络抖动等导致失败,请重新发起新识别。
注意:该问题通常为偶发,少量出现可忽略,发起新识别即可。
5001
因机器负载过高、网络抖动等导致失败,请重新发起新识别。
注意:该问题通常为偶发,少量出现可忽略,发起新识别即可。
5002
因机器负载过高、网络抖动等导致失败,请重新发起新识别。
注意:该问题通常为偶发,少量出现可忽略,发起新识别即可。
6001
境外调用请前往 腾讯云国际站 开通服务。国内站用户请检查是否使用境外代理,如果使用请关闭。