# 一、接口说明

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

# 二、接口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 打分系数,调整打分的松紧度,值越大打分越宽松

# 3.中文API

# 中文评测

{
  "EvalType": "sentence",
  "Language":"cn",
  "displayText": "你好",
  "appkey": "联系商务同学获取",
  "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)