语音识别|ai平台|ai开放平台-云知声口语评测

一、接口说明
二、接口Demo
三、接口要求
四、接口调用流程
五、错误码

# 一、接口说明

基于语音识别和评价技术对发音做客观打分，反馈发音正误和定位问题，有助于语音教学，发音练习，也可测试考生的口语水平。

# 二、接口Demo

Java示例demo (opens new window)
python3示例demo (opens new window)
js示例demo (opens new window)

# 三、接口要求

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

内容	说明
请求协议	ws[s]（为提高安全性，强烈推荐wss）
请求地址	英文：ws://ws-edu.hivoice.cn:8081/ws/eval/或wss://wss-edu.hivoice.cn:443/ws/eval/ 中文：ws://wscn-edu.hivoice.cn:18081/ws/eval/或wss://wsscn-edu.hivoice.cn/ws/eval/
字符编码	UTF-8
响应格式	统一采用JSON格式
开发语言	任意，只要可以向服务发起Websocket请求的均可
操作系统	任意
音频属性	采样率16K，比特率16bit、单声道
音频格式	mp3，wxspeex 或pcm，推荐使用mp3格式
评测语言	中文/英文

# 四、接口调用流程

时序图
avatar

# 1.请求地址

英文
主域名：ws-edu.hivoice.cn
端口：8081
请求地址：ws://ws-edu.hivoice.cn:8081/ws/eval/或wss://wss-edu.hivoice.cn:443/ws/eval/

中文
主域名：wscn-edu.hivoice.cn
端口：18081
请求地址：ws://wscn-edu.hivoice.cn:18081/ws/eval/或wss://wsscn-edu.hivoice.cn/ws/eval/

# 2.英文API

# 普通评测

{
  "mode": "word",
  "displayText": "hello world",
  "appkey": "联系商务同学获取",
  "scoreCoefficient": "1",
  "userID": "",
  "audioFormat": "opus",
  "eof": "gnh-test-end"
}

1
2
3
4
5
6
7
8
9

# jsgf接口

{
  "mode": "qa",
  "Version": "1",
  "DisplayText": "Jsgf Grammar Tool Generated",
  "GrammarWeight": "{\"weight_struct\":[[{\"weight\":0.5,\"key\":\"good morning\"}]]}",
  "Grammar": "#JSGF V1.0 utf-8 cn;\ngrammar main;\npublic <main> = \"<s>\"(<a>|<a> to you)\"</s>\";\n<a> = (good morning);\n",
  "Appkey": "",
  "scoreCoefficient": "1",
  "UserID": "",
  "eof": "test-end",
  "audioFormat": "pcm"
}

1
2
3
4
5
6
7
8
9
10
11
12

# 枚举接口

{
  "mode": "qa",
  "version": "1",
  "displayText": "Enumerate Grammar Tool Generated",
  "grammarWeight": "{\"weight_struct\":[[{\"weight\":0.5,\"key\":\"teacher\"}]]}",
  "grammar": "#enumerate \nmy mother is a teacher\na teacher\n",
  "appkey": "",
  "scoreCoefficient": "1",
  "userID": "",
  "eof": "test-end",
  "audioFormat": "pcm"
}

1
2
3
4
5
6
7
8
9
10
11
12

# retell接口

{
  "mode": "retell",
  "Version": 1,
  "EvalType": "en.exam.retell",
  "DisplayText": "OralComposition Grammar Tool Generated",
  "Language": "en",
  "Grammar": "",
  "GrammarWeight": "{\"weight_struct\":[[{\"weight\":0.5,\"key\":\"bookstore\"}]]}",
  "Reference": {
    "ID": "",
    "answers": [
      {
        "type": 1,
        "text": "bookstore"
      },
      {
        "type": 1,
        "text": "she is going to bookstore"
      }
    ]
  },
  "Appkey": "",
  "scoreCoefficient": "1",
  "UserID": "",
  "eof": "test-end"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

英文评测请求接口字段说明(关键字不区别大小写)

字段	是否必选	含义	备注
mode	必填	可选值为word,sent,para,qa,retell
displayText	必填	评测文本
appkey	必填	秘钥信息	AppKey@AppSecret形式，AppKey和AppSecret 请在应用详情获取
userID	可选	用户id信息	建议传入，排查问题方便
audioFormat	必填	可选值：mp3,speex 音频格式，音频16K单声道
eof	必填	设置eof消息包内容	客户端需要保证该内容的唯一性，可选用uuid
scoreCoefficient	可选	值范围：0.6-1.9	打分系数，调整打分的松紧度，值越大打分越宽松，默认值1.5
repeat	可选	该字段设定多读是否扣分，默认值为0	值为： 0：基础得分60分以上则多读不扣分，低于60分多读扣分； 1：不论基础得分多少，多读均不扣分； 2：无论基础分是多少，多读扣分，直到扣为0分

# 3.中文API

# 中文评测

{
  "EvalType": "sentence",
  "Language":"cn",
  "displayText": "你好",
  "appkey": "联系商务同学获取，或是从AI开放平台创建应用获取",
  "scoreCoefficient": "1",
  "userID": "",
  "audioFormat": "mp3",
  "eof": "gnh-test-end"
}

1
2
3
4
5
6
7
8
9
10

中文评测请求接口字段说明(关键字不区别大小写)

字段	是否必选	含义	备注
EvalType	必填	可选值为word,sentence,paragraph
Language	必填	语种，可选值为cn
displayText	必填	评测文本
appkey	必填	秘钥信息	AppKey@AppSecret形式，AppKey和AppSecret 请在应用详情获取
userID	可选	用户id信息	建议传入，排查问题方便
audioFormat	必填	可选值：mp3,speex 音频格式，音频16K单声道
eof	必填	设置eof消息包内容	客户端需要保证该内容的唯一性，可选用uuid
scoreCoefficient	可选	值范围：0.6-1.9	打分系数，调整打分的松紧度，值越大打分越宽松

# 响应接口

{
  "result": {},
  "area": "sh",
  "time": "1551409712576231666",
  "sid": "f4376e83-7ad0-4635-9812-bec949a2fa27",
  "errcode": 0,
  "errmsg": "ok"
}

1
2
3
4
5
6
7
8

响应接口字段说明

字段	含义	备注
result	评测结果	Json字段说明
area	返回实际评测的的机房区域
time	时间戳
sid sessionID	服务端返回的唯一标识
errorcode	错误码
errmsg	错误消息

评测返回结果中Json字段说明

名称	类型	说明
version	string	结果格式版本及版本号
lines	array	每行输入文本的评测结果
EvalType	string	评测类型：general（朗读评测）、askandanswer（情景问答）、composition（作文）
sample	string	输入的标准文本
usertext	string	用户实际朗读的文本（语音识别结果）
subwords	array	包含单词的音标、开始时间、结束时间、分数、音量信息
begin	double	开始时间，单位为秒
end	double	开始时间，单位为秒
volume	double	音量
score	string	分值
subtext	string	音标或重音符号信息
integrity	double	录入语音的完整度
pronunciation	double	录入语音的标准度
fluency	double	录入语音的流利度
words	array	每个词的评测结果
text	string	单词或音素文本
type	int	类型，共有6种类型，分别是： 0 多词：仅B，C，G模式出现，当朗读内容大于文本内容时，多余的单词type值为0；eg：文本：nice to meet you，音频：nice nice to meet you，第二个nice的type值为0； 1 漏词：所有模式都有，当朗读内容小于文本内容时，未读的单词type值为1；eg：文本：nice to meet you，音频：nice meet you，结果中to的type值为1； 2 正常词：所有模式都有，识别正常的词； 3 错误词：仅B，C，G模式出现，当朗读的文本某个单词识别成文本中其他单词时，该单词type值为3。 eg：文本：nice to meet you，音频：nice you meet you，结果中第一个you的type值为3； 4 静音：所有模式； 5 重复词：预留接口，未实现； 7 空格or标点：仅E模式，空格和标点的结构type值为7； 8 生词：所有模式
sentSample	array	句式标准文本
sentScore	array	句式总分
sentPronunciation	array	句式标准度得分
sentFluency	array	句式流利度得分
sentIntegrity	array	句式完整度得分
keySample	array	关键词sample（包括关键词和每个关键词的得分
keysScore	array	关键词总分
keysPronunciation	array	关键词标准度得分
keysIntegrity	array	关键词完整度得分
keysFluency	array	关键词流利度
standardScore	string	客户定制，输出的分制，当前含有4分制和8分制
StressOfSent	string	句子重读，每个单词都输出，0：该单词没有被重读；1：该单词被重读
StressOfWord	string	单词重音，将用户发音和词典的重音位置做比较，0：该单词重音朗读错误；1：该单词重音朗读正确
tone	array	输出全部信息，数据可以用于画用户的发音曲线，目前只有内部在使用
audiocheck	array	音质检测结果。 volume：音量过小的置信度； clipping：截幅的置信度； noise：噪音过大的置信度； cut:截断的置信度； too short：是否音频过短； emptyAudio：是否是空音频。备注：置信度的值为0和10，10代表可能存在该项音质问题，0代表该项检测正常

# 拼接评测audio url

想要获取用户录音结果，则可以根据响应接口数据拼接音频url，获取音频
"area": "sh",
"time": "1551409712576231666",
"sid": "f4376e83-7ad0-4635-9812-bec949a2fa27",
其中，sh是代表地域名称area，1551409712576231666是代表createtime； f4376e83-7ad0-4635-9812-bec949a2fa27是代表请求中传入的session-id
最后可以根据以上三个信息拼接url，固定字段http://edu.hivoice.cn:9088/WebAudio-1.0-SNAPSHOT/audio/play/{session-id}/{createtime}/{area}
以上示例，最后拼接的url是http://edu.hivoice.cn:9088/WebAudio-1.0-SNAPSHOT/audio/play/ 02055555-f4cd-4fef-8ed8-1a2089056acf/1542272221203805792/sh
如果是https协议，拼接按照 https://edu.hivoice.cn/WebAudio-1.0-SNAPSHOT/audio/play/{session-id}/{createtime}/{area}

# 五、错误码

错误码查询 (opens new window)

← WebAPI文档 http文档 →