注意：此接口为 API 2.0 版本，在参数风格、错误码等方面有区别于 API 3.0 版本，请知悉。
接口描述
本接口服务采用 websocket 协议，对实时音频流进行识别，能够过滤虚拟号平台转接语音，并在毫秒级快速识别真人用户接听状态并返回结果，帮助客户判断对话机器人的启动时机。
在使用该接口前，需要 开通语音识别业务，并进入 API 密钥获取 新建密钥，生成 AppID、SecretID 和 SecretKey，用于 API 调用时生成签名，签名将用来进行接口鉴权。
该接口属于ASR+系列产品，为独立接口，请前往 计费概述 了解此接口计费规则。
接口要求
集成虚拟号真人判定 API 时，需按照以下要求。
| 内容 | 说明 |
|---|---|
| 适用地区 | 仅支持中国大陆地区 |
| 支持行业 | 智能外呼等电话通信行业 |
| 音频属性 | 采样率：8000Hz 采样精度：16bits 声道：单声道（mono） |
| 音频格式 | pcm、wav、opus、speex、silk、mp3、m4a、aac |
| 请求协议 | wss 协议 |
| 请求地址 | wss://asr.cloud.tencent.com/asr/virtual_number/v1/ |
| 接口鉴权 | 签名鉴权机制，详见 签名生成 |
| 响应格式 | 统一采用 JSON 格式 |
| 数据发送 | 建议每40ms 发送40ms 时长（即1:1实时率）的数据包，对应 pcm 大小为：8k 采样率640字节 音频发送速率过快超过1:1实时率或者音频数据包之间发送间隔超过6秒，可能导致引擎出错，后台将返回错误并主动断开连接 |
| 并发限制 | 默认单账号限制并发数为200路 |
接口调用流程
接口调用流程分为两个阶段：握手阶段和识别阶段。两阶段后台均返回 text message，内容为 json 序列化字符串，以下是格式说明：
| 字段名 | 类型 | 描述 |
|---|---|---|
| code | Integer | 状态码，0代表正常，非0值表示发生错误 |
| message | String | 错误说明，发生错误时显示这个错误发生的具体原因，随着业务发展或体验优化，此文本可能会经常保持变更或更新 |
| voice_id | String | 音频流唯一 id，由客户端在握手阶段生成并赋值在调用参数中 |
| message_id | String | 本 message 唯一 id |
| result | Integer | 接听识别结果。 0:真人用户尚未接听 1:真人用户已接听 |
| final | Integer | 该字段返回1时表示音频流全部识别结束 |
握手阶段
请求格式
握手阶段，客户端主动发起 websocket 连接请求，请求 URL 格式为：
wss://asr.cloud.tencent.com/asr/virtual_number/v1/<appid>?{请求参数}<appid>需替换为腾讯云注册账号的 AppID，可通过 API 密钥管理平台 获取，{请求参数}格式为key1=value2&key2=value2...(key 和 value 都需要进行 urlencode)参数说明
| 参数名称 | 必填 | 类型 | 描述 |
|---|---|---|---|
| secretid | 是 | String | 腾讯云注册账号的密钥 SecretId，可通过 API 密钥管理平台 获取 |
| timestamp | 是 | Integer | 当前 UNIX 时间戳，单位为秒。如果与当前时间相差过大，会引起签名过期错误 |
| expired | 是 | Integer | 签名的有效期截止时间 UNIX 时间戳，单位为秒。expired 必须大于 timestamp 且 expired - timestamp 小于90天 |
| nonce | 是 | Integer | 随机正整数。用户需自行生成，最长10位 |
| voice_id | 是 | String | 音频流识别全局唯一标识，一个 websocket 连接对应一个，用户自己生成（推荐使用 uuid），最长128位。 |
| voice_format | 否 | Integer |
语音编码方式，可选，默认值为4。1：pcm；4：speex(sp)；6：silk；8：mp3；10：opus；12：wav；14：m4a（每个分片须是一个完整的 m4a 音频）；16：aac |
| signature | 是 | String | 接口签名参数 |
| wait_time | 否 | Integer | 接通等待时长，默认为30秒，最长60秒，识别超过等待时长返回未接通。 |
signature 签名生成
- 对除 signature 之外的所有参数按字典序进行排序，拼接请求 URL 作为签名原文，这里以 Appid=125922，SecretId=**Qq1zhZMN8dv0** 为例拼接签名原文，则拼接的签名原文为：
asr.cloud.tencent.com/asr/virtual_number/v1/125922***?expired=1673494772&needvad=1&nonce=1673408372&secretid=*****Qq1zhZMN8dv0******×tamp=1673408372&voice_format=1&voice_id=c64385ee-3e5c-4fc5-bbfd-7c71addb35b0 - 对签名原文使用 SecretKey 进行 HmacSha1 加密，之后再进行 base64 编码。例如对上一步的签名原文， SecretKey=*SkqpeHgqmSz*，使用 HmacSha1 算法进行加密并做 base64 编码处理：
得到 signature 签名值为：Base64Encode(HmacSha1("asr.cloud.tencent.com/asr/virtual_number/v1/125922***?expired=1673494772&needvad=1&nonce=1673408372&secretid=*****Qq1zhZMN8dv0******×tamp=1673408372&voice_format=1&voice_id=c64385ee-3e5c-4fc5-bbfd-7c71addb35b0", "*****SkqpeHgqmSz*****"))G8jDQBRg1JfeBi/YnTjyjekxfDA= - 将 signature 值进行 urlencode（必须进行 URL 编码，否则将导致鉴权失败偶现 ）后拼接得到最终请求 URL 为：
wss://asr.cloud.tencent.com/asr/virtual_number/v1/1259228442?expired=1592380492&filter_dirty=1&filter_modal=1&filter_punc=1&needvad=1&nonce=1592294092123&secretid=AKIDoQq1zhZMN8dv0psmvud6OUKuGPO7pu0r×tamp=1592294092&voice_format=1&voice_id=RnKu9FODFHK5FPpsrN&signature=HepdTRX6u155qIPKNKC%2B3U0j1N0%3D
Opus 音频流封装说明
压缩 FrameSize 固定640，即一次压缩640 short，否则解压会失败。传到服务端可以是多帧的拼接组合，每一帧需满足下面格式。
每一帧压缩数据封装如下：
| OpusHead（4字节） | 帧数据长度（2字节） | Opus 一帧压缩数据 |
|---|---|---|
| opus | 长度 len | 对应 len 长的 opus decode data |
请求响应
客户端发起连接请求后，后台建立连接进并进行签名校验，校验成功则返回 code 值为0的确认消息表示握手成功；如果校验失败，后台返回 code 为非0值的消息并断开连接。
{"code":0,"message":"success","voice_id":"RnKu9FODFHK5FPpsrN"}识别阶段
握手成功之后，进入识别阶段，客户端上传语音数据并接收识别结果消息。
上传数据
在识别过程中，客户端持续上传 binary message 到后台，内容为音频流二进制数据。建议每40ms 发送40ms 时长（即1:1实时率）的数据包，对应 pcm 大小为：8k 采样率640字节。音频发送速率过快超过1:1实时率或者音频数据包之间发送间隔超过6秒，可能导致引擎出错，后台将返回错误并主动断开连接。
音频流上传完成之后，客户端需发送以下内容的 text message，通知后台结束识别。
{"type": "end"}接收消息
客户端上传数据的过程中，需要同步接收后台返回的实时识别结果，如果返回识别结果，则表示已经识别完成，客户端无需再继续给后台发送消息，结果示例：
{"code":0,"message":"success","voice_id":"CzhjnqBkv8lk5pRUxhpX","message_id":"CzhjnqBkv8lk5pRUxhpX_241","final": "1", "result": 1}{"code":4008,"message":"后台识别服务器音频分片等待超时","voice_id":"CzhjnqBkv8lk5pRUxhpX","message_id":"CzhjnqBkv8lk5pRUxhpX_241"}错误码
| 数值 | 说明 |
|---|---|
| 4001 | 参数不合法，具体详情参考 message |
| 4002 | 鉴权失败 |
| 4003 | AppID 服务未开通，请在控制台开通服务 |
| 4004 | 无可使用的免费额度 |
| 4005 | 账户欠费停止服务，请及时充值 |
| 4006 | 账号当前调用并发超限 |
| 4007 | 音频解码失败，请检查上传音频数据格式与调用参数一致 |
| 4008 | 客户端数据上传超时 |
| 4009 | 客户端连接断开 |
| 4010 | 客户端上传未知文本消息 |
| 5000 | 后台错误，请重试 |
| 5001 | 后台识别服务器识别失败，请重试 |
| 5002 | 后台识别服务器识别失败，请重试 |
