口语评测功能说明文档
文档状态
| 文件标识： | TuringOS-Oral-V1.1.2 |
|---|---|
| 系统版本： | OpenSocket |
| 完成日期： | 2021年11月10日 |
文档修订记录
为便于后续文档维护，文档版本号将由三部分组成，第一个数字为主版本号，第二个数字为功能版本号，第三个数字为修订版本号：
| 文档版本号 | 修订日期 | 修订原因 |
|---|---|---|
| V1.1.1 | 2021.4.23 | 创建文档 |
| V1.1.2 | 2021.11.10 | 在第6小节result字段中增加原声音频参数（originalAudio） |
协议说明
1.域名地址
正式环境：ws://ws-api.turingapi.com/api/v2
2.加密说明
为保证接口的安全性和稳定性，需要对接口数据进行加密；
- 加密必须包含的信息：APIkey，Secret（需通过图灵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",
"service_identify": "scanPen",
"data": "加密后的内容"
}
3.1 初始化参数
data加密前数据格式:
{
"deviceId": "ai000***00",
"requestType": [1],
"nlpRequest": {
"content": [{
"type": 5,
"data": "6217ea26a7a84351a85138b6b89dd398",
"binaryDetail": {
"name": "hello",
"type": "wav",
"ext": {
"channel": 1,
"sampleRate": 16000,
"sampleBytes": 2
}
}
}],
"clientInfo": {
"appState": {
"code": 1000047,
"operateState": 1100
}
},
"binarysState": {
"openBinarysId": "6217ea26a7a84351a85138b6b89dd398"
}
}
}
3.2 上传评测音频
初始化成功后，上传需要评测的音频数据；
（注：每段传输数据小于1024*8 byte，录音时长不超过10s）
3.3 结束本次评测
data加密前数据格式:
{
"binarysState": {
"completeBinarysId": "6217ea26a7a84351a85138b6b89dd398"
}
}
4.请求参数说明
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| key | String | Y | apiKey，需官网申请； |
| timestamp | String | Y | 时间戳 |
| data | Json | Y | 配置信息，加密后的请求数据，加密参考：加密方式 |
| service_identify | String | N | 场景模式 不输入场景默认时，为普通场景 当输入scanPen时，为扫读笔场景 |
当使用service_identify字段，为扫读笔场景时：
- 参数值只有是scanPen才会生效，输入其他值均为普通场景；
- 普通场景无法使用OCR能力，会提示OCR权限异常。
data字段说明
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| deviceId | String | Y | 用户设备Id: 由字母或数字组成，其他字符可能导致部分功能错误，长度等于16位。 |
| requestType | Array | Y | 该次请求需要请求的内容：0:ASR，1:NLP，2:TTS |
| nlpRequest | Json | Y | nlp内容请求信息 |
| binarysState | Json | N | 二进制参数上传状态 |
nlpRequest - content字段说明
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| type | int | N | 输入类型: type=0为文本（默认） type=1为图片 type=2为音频 type=5为口语评测 |
| data | String | Y | 当type=0，可直接输入文本内容 当type=其他值，需输入二进制参数：32位字符串(UUID) |
| binaryDetail | String | Y | 二进制参数说明 |
注意:
- Socket的二进制参数输入，都需要初始化时在nlpRequest-content中提前申明，并将代表该二进制参数ID赋值给nlpRequest-content-data；
- 32位字符串(UUID)：自己生成一个32位的唯一值进行上传就可以，主要用于向云端告知要上传的文件；
content - binaryDetail字段说明
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| name | String | N | 口语评测文本 |
| type | String | N | 文件类型 支持wav，mp3，amr(默认为"mp3"格式) |
| ext-channel | Integer | N | 音频声道数 单声道：1，多声道：2 |
| ext-sampleRate | Integer | N | 音频采样率 如果是本地音频评测，需要传入相应的音频采样率（默认为 "16K"） |
| ext-sampleBytes | Integer | N | 采样字节 8bit的采样字节传1，16bit采样字节传2（默认为"2"） |
binaryDetail 不传时，默认为MP3格式，channel=2，sampleRate=16000，sampleBytes=2
ClientInfo字段说明
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| appState | AppState | N | 客户端状态 |
ClientInfo - appState字段说明
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| code | int | N | 技能code |
| operateState | int | N | 应用状态 operateState=1100 : 英文单词 operateState=1101 : 英文句子 operateState=1120 : 中文汉字 operateState=1121 : 中文句子 |
binarysState字段说明
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| openBinarysId | String | N | 将要上传的文件参数：32位字符串 （该值与nlpRequest-content-data字段中的UUID一致） |
| completeBinarysId | String | Y | 已完成上传的文件参数：32位字符串 （该值与nlpRequest-content-data字段中的UUID一致） |
补充说明：
openBinarysId：在初始化时使用该字段，主要为了告知云端，将要上传一个二进制文件，需要云端准备接收；
completeBinarysId：在上报结束标识时使用该字段，主要为了告知云端，已上传完二进制文件，云端不需要再等待接收文件；
5.返回示例
以返回单词为例：
{
"code": 200,
"globalId": "8032******158001",
"nlpResponse": {
"intent": {
"code": 1000047,
"operateState": 1100,
"parameters": {
"result": {
"pron": 0,
"overall": 0,
"details": [{
"score": 0,
"phone": [{
"score": 0,
"char": "hh"
}, {
"score": 0,
"char": "ax"
}, {
"score": 0,
"char": "l"
}, {
"score": 0,
"char": "ow"
}],
"char": "hello",
"start": 170,
"end": 430
}],
"info": 0,
"wavetime": 2540
},
"code": 0,
"refText": "hello",
"originalAudio": "http://book-iot-cdn.turingos.cn/202111101700/c0d2c829c41667693528228c5bacd0f8/dict/oralEnglishTest/acb6d152fe2d4f528d47db97c38c3387_69475122_158363316247262001_7da2d019a25e44e8b594de3e6101d30f.pcm"
}
},
"results": [{
"groupType": 0,
"resultType": "text",
"values": {
"text": "评测完成,你的得分为:0.0"
}
}]
}
}
6.返回参数说明
| 标签 | 类型 | 是否必须 | 含义 |
|---|---|---|---|
| code | int | Y | 返回码 |
| globalId | String | Y | 评测结果ID，用于排查问题 |
| nlpResponse | Json | Y | nlp相关回复信息 |
Intent字段说明
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| code | int | Y | 输出应用code |
| operateState | int | Y | 应用状态 |
| parameters | Json | Y | 评测结果 |
operateState 字段说明
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| operateState | int | Y | 1010：英文单词 1011：英文句子 1020：中文汉字 1021：中文句子 |
parameters字段说明
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| result | Json | Y | 评测结果说明 |
| code | int | Y | 输出识别code |
| refText | String | Y | 评测文本 |
| originalAudio | String | Y | 评测原声音频（用户的声音） |
result字段说明
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| pron | Int | Y | 发音得分 |
| overall | Int | Y | 总得分 |
| integrity | Int | N | 完成度评分: 单词测评时无该字段 |
| fluency | Int | N | 流利度得分: 单词测评时无该字段 |
| rhythm | Int | N | 韵律性评分: 单词测评时无该字段 |
| wavetime | Int | N | 音频长度: 单词测评时无该字段 |
| details | Array[json] | Y | 详细的测评信息,具体见details字段说明 |
details字段说明
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| score | Int | Y | 得分 |
| char | String | Y | 评测的单词 |
| start | Int | Y | 音频文件处理的开始地址；无需关注 |
| end | Int | Y | 音频文件处理的结束地址；无需关注 |
| phone | Array[json] | Y | 单个字母评测信息,具体见phone字段说明 |
phone字段说明
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| score | Int | Y | 得分 |
| char | String | Y | 评测的字母 |
result字段说明
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| groupType | int | Y | 组类型(普通接入可忽略该参数) 0为独立输出； 大于0时可能包含同组相关内容 |
| resultType | String | Y | 输出类型 文本(text)； 链接(url)； 音频(voice)； 动作表情(action)； 视频(video)； 图片(image)； 图文(news)； |
| values | Map | Y | 输出内容 |
附录：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引擎异常超时 |
| 5007 | ASR数据传输失败，没有初始化 |
| 5008 | ASR二进制数据转码失败 |
| 5010 | ASR不支持混合模式识别 |
| 5100 | 评测启动失败，请稍后再试 |
| 5101 | 评测状态错误，请正确上传文件 |
| 5102 | 评测类型非法 |
| 5103 | 评测内容为空 |
| 5104 | userid并发请求测评功能 |
| 5105 | 测评失败，请查看错误信息 |
| 6000 | 丢弃任务：同一用户不允许同时处理一个以上的ASR请求 |
注意 * 4XXX~5XXX异常，服务端将主动关闭与客户端的connection，其余code不会关闭；