语音识别WebAPI 文档

语音识别介绍

语音识别可以将音频准确地识别成文字，支持中文普通话和英文。

接口Demo

部分接口demo如下：

java语言demo参考

集成websocket请求时，需按照以下要求：

内容	说明
传输方式	ws[s] (若对数据通信有较高的安全要求，建议选择wss接入方式来访问图灵服务，由于ssl层验证预计会额外多花费40\~50ms的时间。)
请求地址	ws[s]://ws-api.turingapi.com/api/v2
字符编码	UTF-8
响应格式	json
支持识别文本语言	中文，英文
支持机器人类型	SDK接入（Android）、WebSocket接入、混合SDK接入（Android）、混合SDK接入（Linux）
是否支持并发	SOCKET不允许并发请求，即上一轮请求未完成(result-done)时不允许发送下一个请求。
支持音频格式	pcm，opus，speex

数据加密方式

加密说明

API接口默认不加密（Biz平台可选择加密状态），为保证接口的安全性和稳定性，可对接口数据进行加密；

AES加密方式详见：

加密模式 CBC
填充 PKCS5Padding
数据块 128位(密钥为16位)
输出 base64编码字符串
编码 utf-8
密钥 apikey+图灵官网机器人详情页Secret+当前毫秒时间戳(取输入参数)-->对该字符串取16位小写md5值
(参考 https://www.sojson.com/encrypt_md5.html)

注：偏移量字符串等于密钥

加密参考页面 http://tool.chacuo.net/cryptaes

加密后主要代码：

String data="加密前内容";
//加密方法
data=AesUtils.getTlAes(apiKey, apiSecret, time).encrypt(data);

加密后请求示例如下：

{
  "data":"加密后的内容",
  "key":"ed474dae62*********67050faea1788",
  "timestamp":"150******7793"
}

请求参数说明

参数	类型	是否必须	说明
key	String	Y	biz平台设置机器人的apiKey
timestamp	String	Y	时间戳
data	JSON	Y	配置信息，参考下方参数data字段说明

data字段说明

参数	类型	是否必须	说明
deviceId	String	Y	用户设备id. 要求:1,长度小于等于32位。 2,需由字母或数字组成，其他字符可能导致部分功能错误
requestType	Array	Y	asr需要请求的内容固定应该为[0] : 0\:ASR 1\:NLP 2\:TTS
nlpRequest	Json	Y	nlp内容请求信息，参考下方参数nlpRequest字段说明

asrRequest	Json	N	请求asr时需要的参数
binarysState	Json	N	二进制参数上传状态

data - nlpRequest字段说明

参数	类型	是否必须	说明
content	json	Y	输入信息，参考下方参数nlpRequest - content字段说
clientInfo	json	N	客户端状态，参考下方 nlpRequest - clientInfo 字段说明
userInfo	json	N	用户参数，参考下方 nlpRequest - userInfo 字段说明

nlpRequest - content 字段说明

参数	类型	是否必须	说明
type	int	N	输入类型， type=0-文本 type=1-图片 type=2-音频(asr) type=5-音频(技能）
data	String	Y	若type=0则对应是输入的文本，非0是对应类型的二进制参数ID：32位字符串(UUID)

nlpRequest - userInfo 字段说明

参数	类型	是否必须	取值范围	说明
uniqueId	String	N	deviceId值	可以不传入，或者传入和上方的deviceId保持一致
requestIP	String	N	客户端ip地址	可上传客户端ip地址
useCodes	Array	N	应用code	用户此次交互仅使用该参数中的应用，

nlpRequest - clientInfo 字段说明

参数	类型	是否必须	说明
appState	json	N	客户端状态，开启此字段可以直接进入此技能，关闭同理，参考下方clientInfo - appState 字段说明
robotSkill	json	N	针对应用code的自定义参数，参考下方 clientInfo - robotSkill 字段说明

clientInfo - appState 字段说明

参数	类型	是否必须	说明
code	int	Y	应用code
operateState	int	Y	请求应用时的状态值（与输出的operateState无关）

clientInfo - robotSkill 字段说明

参数	类型	是否必须	说明
key	String	N	应用code， asr的code =9090508
value	JSON	N	key应用使用的自定义参数

asrRequest字段说明

参数	类型	是否必须	说明
asrFormatEnum	int	Y	音频格式: asrFormatEnum=0\:PCM asrFormatEnum=1\:OPUS asrFormatEnum=2\:SPEEX
asrLanguageEnum	int	Y	语言: asrLanguageEnum=0:中文 asrLanguageEnum=1:英文
asrRateEnum	int	Y	音频采样率: asrRateEnum=0:8k(PCM) asrRateEnum=1:16k(PCM, OPUS, SPEEX)
intermediateResult	boolean	N	是否返回中间ASR结果（默认false）
enableITN	boolean	N	返回结果的数字格式规则为阿拉伯数字格式(默认true)
enablePunctuation	boolean	N	是否开启标点符号添加(默认true)

opus格式要求:

pcm转为opus裸包之后在头部增加8个字节，其中第3，4字节代表音频片段数据长度{head(8byte 3,4位存数据长度)+data} + {head(8byte 3,4位存数据长度)+data} + ...
每次调用opensocket上传音频片段必须完整
大端模式

binarysState 字段说明

参数	类型	是否必须	取值范围	说明
openBinarysId	String	N	-	将传输二进制数据的参数ID： 1. 该值与nlpRequest-content-data中的内容一致 2. 32位字符串(UUID)
completeBinarysId	String	N	-	完成传输的二进制数据的参数ID： 32位字符串(UUID)

注意:

WebSocket的二进制参数输入都需要初始化时在nlpRequest-content中按类型提前申明并将代表该二进制参数ID赋值给nlpRequest-content-data.

asr识别结果为空时，如果没有其他输入不会请求nlp/tts服务。

输出参数说明

参数说明

参数	类型	是否必须	说明
code	int	Y	状态code；参考状态code列表
globalId	String	Y	请求唯一标识
message	String	Y	code对应的说明；参考状态code列表
nlpResponse	Json	N	nlp相关回复信息，参考nlpResopnse参数说明
asrResponse	Json	N	asr请求相关回复信息；参考asrResponse参数说明

nlpResponse参数说明

参数	类型	是否必须	说明
intent	Intent	Y	请求意图，详细参考下方 nlpResponse - Intent 参数说明
results	Array	N	输出结果集，详细参考nlpResponse - results 字段说明

nlpResponse - Intent 参数说明

参数	类型	是否必须	说明
code	int	Y	输出技能code

nlpResponse - results 字段说明

参数	类型	是否必须	说明
resultType	String	Y	输出类型文本（text）链接（url）音频（voice）视频（video）图片（image）图文（news）动作表情（action）
values	Map	Y	输出内容（必包含key等于resultType的值，详细请查看下方nlpResponse - results -valuse 字段说明
groupType	int	Y	组类型(普通接入可忽略该参数) 0为独立输出; 大于0时可能包含同组相关内容

asrResponse参数说明

参数	类型	是否必须	说明
binarysId	String	Y	asr二进制参数Id
value	String	Y	asr识别内容
state	int	Y	state=200\:asr识别完成结果 state=210\:asr识别中间结果返回

输入输出示例

二进制输入请求示例

初次二进制方式请求时：

{
    "key": "a2ce4f54223548f******3a684681b0c",
    "timestamp": "1585799006000",
    "data": {
        "deviceId": "ai11223344556677",
        "requestType": [
            0
        ],
        "nlpRequest": {
            "content": [
                {
                    "data": "6217ea26a7a84351a85138b6b89dd398",
                    "type": 2
                }
            ]
        },
        "asrRequest": {
            "asrFormatEnum": 0,
            "asrLanguageEnum": 0,
            "asrRateEnum": 1,
            "enableITN": true,
            "enablePunctuation": true
        },
        "binarysState": {
            "openBinarysId": "6217ea26a7a84351a85138b6b89dd398"
        }
    }
}

请求结束后的请求：

{
    "key": "a2ce4f54223548f******3a684681b0c",
    "timestamp": "1585799006000",
    "data": {
        "binarysState": {
            "completeBinarysId": "完成传输的二进制参数id"
        }
    }
}

ASR输出结果

{
    "code": 210,
    "done": false,
    "globalId": "219973526858500001",
    "message": "参数初始化成功"
}

{
    "asrResponse": {
        "binarysId": "5d062ef062584c4c89999c0967f05f65",
        "state": 200,
        "value": "欢迎来到图灵平台。"
    },
    "code": 200,
    "done": true,
    "globalId": "219973526858500001",
    "message": "success"
}

附录

状态code列表

code	说明
200	正确结果返回
210	参数初始化成功，请收到该标识后上传二进制数据(如果需要)
220	参数上传完成，正在请求nlp/tts
230	ASR/NLP正确处理，但tts功能处理失败(单独请求TTS功能，异常时也返回该code)
240	输入参数为空，nlp/tts不处理
300	无效数据:二进制参数已完成传输，不要发送该数据
4004	机器人类型非法
4005	apikey信息错误
4006	deviceId信息错误
4007	解密失败，您的加密逻辑存在异常
4008	数据内容格式错误
4009	机器人被禁用
4010	试用期已过
4011	系统不支持二进制参数
4012	今天我们已经聊了很多啦，明天再来找我聊天吧。
4013	这一小时的对话次数已经超过我的极限啦，让我休息一下，待会再聊
4014	这一分钟里我们已经聊了很多啦，休息，休息一下吧
4015	二进制参数错误，请确定binarysId是否对应
4016	单次交互时间过长，请查看文档！
4017	二进制参数错误，有重复binarysId！
4018	二进制参数输入状态异常
4019	二进制参数处理时间超时/第三方引擎参数错误
4020	ASR权限异常
4022	二进制传输内容过大！
4023	单次交互同类型的二进制参数只允许输入一个
4025	上传数据失败，请稍后\~
4027	请求类型不能为空
4028	丢弃任务：同一用户不允许同时处理一个以上的ASR请求
4029	ASR调用次数耗尽
4100	服务正在升级请稍后再试
4101	请求没有正确初始化！
4102	长时间未请求业务,关闭连接
4200	robot信息异常
5001	音频信息参数错误
5002	未上传任何二进制数据
5003	ASR音频格式不支持
5004	ASR引擎链接异常
5005	ASR引擎异常超时
5006	ASR引擎异常
5007	ASR数据传输失败，没有初始化
5008	ASR二进制数据转码失败
6000	丢弃任务：同一用户不允许同时处理一个以上的ASR请求

注意

4XXX\~5XXX异常，服务端将主动关闭与客户端的connection，其余code不会关闭；
音频中间有静音或者杂音音频超过了后端点的设置（vad_eos) ,最大值10000ms，音频识别不完整是正常的；