在线语音识别及翻译接口文档

文档状态

文件标识：	TuringOS-OpenSocket-V1.2
系统版本：	OpenSocket
作者：	段亚骏
完成日期：	2021年6月24日

文档修订记录

文档版本号	修订日期	修订原因	修订人
V1.0	2021.3.12	创建文档	段亚骏
V1.1	2021.3.17	修改中英混合识别开启字段	段亚骏
V1.2	2021.6.24	在文档各级标题中增加有序列表在3.1节请求示例中替换useCodes字段	段亚骏
V1.3	2023.12.23	翻译接口改为1000018	刘秀丽

协议说明

一、请求流程说明

二、协议说明

1.域名地址

正式环境： ws://ws-api.turingapi.com/api/v2

2.加密模式

默认不加密，如需加密在”biz平台-机器人信息页“开启加密模式，开启后需对data字段进行AES加密，参数如下：

参数	说明	备注
加密模式	CBC	-
填充	PKCS5Padding	-
数据块	128位（密钥为16位）	-
密码	secretKey	Apikey+Secret（机器人信息页获取）+ 时间戳(毫秒，与入参一致) 进行Md5加密，取16位小写值
偏移量	secretKey	Apikey+Secret（机器人信息页获取）+ 时间戳(毫秒，与入参一致) 进行Md5加密，取16位小写值
输出	base64编码	-
字符集	utf-8	-

3.请求示例

加密后数据格式:

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

3.1 初始化请求

3.1.1 文本请求翻译

data加密前数据格式:

{
    "deviceId": "123",
    "requestType": [1],
    "nlpRequest": {
        "content": [{
            "data": "Hello World"
        }],
        "userInfo": {
            "useCodes": [1000018]
        }
    }
}

3.1.2 音频请求

data加密前数据格式:

{
    "deviceId": "123",
    "requestType": [0],
    "asrRequest": {
        "asrFormatEnum": 0,
        "asrLanguageEnum": 0,
        "asrRateEnum": 1,
        "enableITN": true,
        "enablePunctuation": true,
        "enableVoiceDetection": false
    },
    "nlpRequest": {
        "content": [{
            "data": "6217ea26-a7a8-4351-a851-38b6b89dd398",
            "type": 2
        }],
        "userInfo": {
            "useCodes": [1000018]
        }
    },
    "binarysState": {
        "openBinarysId": "6217ea26-a7a8-4351-a851-38b6b89dd398"
    }
}

3.1.3 中英ASR混合识别+全文翻译请求

data加密前数据格式:

{
    "deviceId": "123",
    "requestType": [0,1],
    "asrRequest": {
        "asrFormatEnum": 0,
        "asrLanguageEnum": 0,
        "asrRateEnum": 1,
        "enableITN": true,
        "enablePunctuation": true,
        "enableVoiceDetection": false
    },
    "nlpRequest": {
        "content": [{
            "data": "6217ea26-a7a8-4351-a851-38b6b89dd398",
            "type": 2
        }],
        "userInfo": {
            "useCodes": [1000018]
        }
    },
    "binarysState": {
        "openBinarysId": "6217ea26-a7a8-4351-a851-38b6b89dd398"
    }
}

3.2 发送音频数据

初始化成功后，上传需要识别的音频数据；

（注：每段传输数据小于1024*8 byte，上传音频发送间隔不超过10S，单轮音频请求时长不超过60秒）

3.3 结束本次识别

data加密前数据格式:

{
    "data": {
        "binarysState": {
            "completeBinarysId": "完成传输的二进制参数id"
        }
    }
}

4.请求参数说明

参数	类型	是否必须	说明
key	String	Y	apiKey，需官网申请；
timestamp	String	Y	时间戳
data	Json	Y	配置信息，加密后的请求数据，加密参考：加密方式

data字段说明

参数	类型	是否必须	说明
deviceId	String	Y	用户设备Id: 由字母或数字组成，其他字符可能导致部分功能错误，长度等于16位。
requestType	Array	Y	该次请求需要请求的内容：0:ASR，1:NLP，2:TTS
nlpRequest	Json	Y	nlp内容请求信息 1：文本方式请求 2：图片、音频请求
asrRequest	Json	Y	请求asr时需要的参数
binarysState	Json	N	二进制参数上传状态

nlpRequest - content字段说明（文本请求）

参数	类型	是否必须	说明
type	int	N	0：文本（默认，可不填写）
data	String	Y	文本信息

nlpRequest - content字段说明（图片、音频请求）

参数	类型	是否必须	说明
type	int	N	1：图片 2：ASR音频 5：口语评测
data	String	Y	对应类型的二进制参数ID：32位字符串(UUID)

nlpRequest - userInfo字段说明

参数	类型	是否必须	说明
useCodes	Array	N	应用code [1000018]为指定请求全文翻译技能

asrRequest字段说明

参数	类型	是否必须	说明
asrFormatEnum	int	Y	音频格式: 0：PCM 1：OPUS 2：SPEEX
asrLanguageEnum	int	Y	语言: 0：中文（开启后支持中英文混合识别） 1：英文
asrRateEnum	int	Y	音频采样率: 0：8k（PCM） 1：16k（PCM，OPUS，SPEEX）
intermediateResult	boolean	N	是否返回中间ASR结果（默认false）
enableITN	boolean	N	返回结果的数字格式规则为阿拉伯数字格式（默认true）
enablePunctuation	boolean	N	是否开启标点符号添加（默认true)
enableVoiceDetection	boolean	N	是否启动语音检测（默认false）: 启动后需要同时设置maxStartSilence和maxEndSilence的值
maxStartSilence	Integer	N	允许的最大开始静音（单位：毫秒）：超出后服务端将会返回asrResponse.state=200，结束本次识别，需要先设置enableVoiceDetection为true
maxEndSilence	Integer	N	允许的最大结束静音（单位：毫秒）：超出后服务端会将返回asrResponse.state=200，结束本次识别，需要先设置enableVoiceDetection为true

binarysState字段说明

参数	类型	是否必须	说明
openBinarysId	String	N	将传输二进制数据的参数ID：该值与nlpRequest-content-data中的内容一致
completeBinarysId	String	Y	socket完成二进制参数ID(该状态由服务器告知客户端）

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

5.返回示例

{
    "code": 200,
    "done": true,
    "globalId": "171156189262884001",
    "message": "success",
    "nlpResponse": {
        "intent": {
            "code": 100018
        },
        "results": [{
            "groupType": 0,
            "resultType": "text",
            "values": {
                "text": "hello"
            }
        }]
    }
}

6.返回参数说明

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

asrResponse参数说明

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

nlpResponse - Intent字段说明

参数	类型	是否必须	说明
code	int	Y	输出应用code
operateState	int	Y	应用状态(应用单独定义)

nlpResponse - Result字段说明

参数	类型	是否必须	说明
resultType	String	Y	输出类型文本(text)；链接(url)；音频(voice)；动作表情(action)；视频(video)；图片(image)；图文(news)；
values	Map	Y	输出内容
groupType	int	Y	组类型(普通接入可忽略该参数) 0为独立输出；大于0时可能包含同组相关内容

附录：code状态列表

code	说明
200	正确结果返回
210	参数初始化成功，请收到该标识后上传二进制数据(如果需要)
220	参数上传完成，正在请求nlp/tts
240	输入参数为空，nlp/tts不处理
270	测评中间结果
280	测评最终结果
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	上传数据失败，请稍后~
4026	nlp/tts请求内容过长
4027	请求类型不能为空
4028	丢弃任务：同一用户不允许同时处理一个以上的ASR请求
4029	robot ASR调用次数耗尽
4030	robot NLP调用次数耗尽
4031	uri不支持
4032	请求时间戳偏与服务器时间偏差太大，message为服务器时间戳
4100	服务正在升级请稍后再试
4101	请求没有正确初始化！
4102	长时间未请求业务,关闭连接
4200	robot信息异常
4201	nlp/tts处理异常
5001	音频信息参数错误
5002	未上传任何二进制数据
5003	ASR音频格式不支持
5004	ASR引擎链接异常
5005	ASR引擎异常超时
5006	讯飞ASR引擎异常
5007	ASR数据传输失败，没有初始化
5008	ASR二进制数据转码失败
5010	ASR不支持混合模式识别
5100	评测启动失败，请稍后再试
5101	评测状态错误，请正确上传文件
5102	评测类型非法
5103	评测内容为空
5104	userid并发请求测评功能
5105	测评失败，请查看错误信息
6000	丢弃任务：同一用户不允许同时处理一个以上的ASR请求

注意 * 4XXX~5XXX异常，服务端将主动关闭与客户端的connection，其余code不会关闭；