- ···
- 产品服务
- ···
- 解决方案
- ···
- 文档中心
- ···
# 一、接口说明
基于语音识别和评价技术对发音做客观打分,反馈发音正误和定位问题,有助于语音教学,发音练习,也可测试考生的口语水平。
# 二、HTTP接口调用流程
上传文本和音频,获取评测结果。
# 1.请求方法
post
# 2.请求地址
英语评测
普通http评测访问: http://edu.hivoice.cn:8085/eval/{audioFormat} 端口:8085
小程序等https请求访问:https://edu.hivoice.cn/eval/{audioFormat} 默认端口:443
中文评测
普通http评测访问:http://cn-edu.hivoice.cn/eval/{audioFormat} 端口:80
小程序等https请求访问:https://cn-edu.hivoice.cn/eval/{audioFormat} 默认端口:443
备 注:请求的URL中的{audioFormat}需跟上传的音频格式对应,例如amr格式的音频对应英语评测地址为 http://edu.hivoice.cn:8085/eval/amrnb audioFormat可选值:mp3/silk/opus/amrnb/wxspeex/ogg/aac/pcm/wav,wav和pcm请求地址的后缀均为pcm
audioFormat说明
参数名 | 是否必须 | 说明 |
---|---|---|
audioFormat | 必须 | 音频格式,可选值: mp3 , silk , opus , amrnb ,wxspeex, ogg, aac,pcm, wav. 音频采用 8K/16K采样率 位长16Bit编码方式生成,不支持双声道 连续的opus帧,每帧有两个字节的小端头,每个opus帧由640 bytes pcm编码得到;或窄带amr Example: opus. mp3音频中不能含有tag信息,所谓Tag 信息,就是在MP3文件中加入曲名、演唱者、专集、年月、流派、注释等信息,不支持双声道音频。 对于mp3,一般是建议采样率设置为16K,比特率设置为64 kbps |
# 3.参数说明
header
参数名 | 是否必须 | 说明 |
---|---|---|
session-id | 必须 | 表示该次评测的唯一表示,使用 uuid |
appkey | 必须 | AppKey@AppSecret形式,AppKey和AppSecret 请在应用详情获取 |
score-coefficient | 选填 | 分数调整定制参数,可以对同样质量的语音调整得分高低,范围是0.6~1.9,默认情况下是1.5,设置越低,打分越严格,设置系数越高,打分越松,一般小学生设置系数偏高,采取鼓励模式。 |
device-id | 选填 | 设备或用户的id标识。一个客户应该保证每个用户拥有唯一的id |
Wrap-Create-Time | 必须 | 值为 true 添加此请求头, 返回结果将会添加sessionId和和createTime (结构见具体返回) 注意:js解析时间精度会丢失,请将时间转字符串后再解析。 |
X-EngineType | 选填 | 值为:oral.zh_CH 这个是中文评测时需要添加的请求头, 仅当使用中文评测时添加此请求头 |
text-type | 选填 | 值为:json 如果传入的text是json格式,该参数判断格式是否正确,json格式不正确则返回错误码,一般不填写 |
repeat | 选填 | 该字段设定多读是否扣分。默认值为0。值为: 0:基础得分60分以上则多读不扣分,低于60分多读扣分; 1:不论基础得分多少,多读均不扣分; 2:无论基础分是多少,多读扣分,直到扣为0分 |
body
参数名 | 是否必须 | 说明 |
---|---|---|
text | 必填 | 需要评测的文本 string格式 |
mode | 必填 | 评测模式(包含A B C D E G H,A B G H 是常用模式) 英文支持的模式 A:最简单模式,结果只有单词打分没有音素信息 B:有音素信息,但是没有音素打分 C:跟A一样,同时适用于篇章打分 D:在B的基础上,有音素打分 E:返回words字段里的值,有空格和标点符号,也包含音素打分 G:跟D一样 H:选择题打分模式 单词句子跟读推荐E模式,其他推荐C模式 中文仅支持E模式: E:返回words字段里的值,支持声母、韵母和声调的输出 |
voice | 必填 | 语音数据,multipart ;如果音频存在oss上,则将voice参数改为voiceurl,值为音频的在线url地址 |
请求示例
#ZH-Oral
curl -X POST -H "session-id:`uuidgen`" -H "appkey:www" -H "Content-Length" -H "device-id:userid" -H "X-EngineType:oral.zh_CH" --form text="学而时习之,不亦说乎。 --form mode="B" --form voice=@'test.opus' "http://cn-edu.hivoice.cn/eval/opus"
#EN-Oral
curl -X POST -H "session-id:`uuidgen`" -H "appkey:www" -H "Content-Length" -H "device-id:userid" --form text="good" --form mode="A" --form voice=@'good.opus' "http://edu.hivoice.cn:8085/eval/opus"
1
2
3
4
5
2
3
4
5
Java 示例
import org.springframework.core.io.FileSystemResource;
import org.springframework.http.*;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.client.RestTemplate;
import java.io.File;
import java.nio.charset.Charset;
import java.util.UUID;
public class springHttp {
public static void main(String[] args) throws Exception {
RestTemplate rest = new RestTemplate();
//api url地址
String url = "http://edu.hivoice.cn:8085/eval/mp3";
//post请求
HttpMethod method = HttpMethod.POST;
MultiValueMap<String, Object> parts = new LinkedMultiValueMap<>();
parts.add("mode", "A");
parts.add("text", "hello, i am nice to meet you");
FileSystemResource resource = new FileSystemResource(new File("D:\\sh.mp3"));
parts.add("voice", resource);
client(url, HttpMethod.POST, parts);
}
public static String client(String url, HttpMethod method, MultiValueMap<String, Object> params) {
RestTemplate client = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
headers.set("appkey", "xxxx");
headers.setContentType(MediaType.parseMediaType("multipart/form-data;charset=UTF-8"));
String uuid_str = UUID.randomUUID().toString();
headers.set("session-id", uuid_str);
headers.set("device-id", "userid");
HttpEntity<MultiValueMap<String, Object>> requestEntity = new HttpEntity<MultiValueMap<String, Object>>(params, headers);
// 执行HTTP请求
ResponseEntity<String> response = client.exchange(url, HttpMethod.POST, requestEntity, String.class);
System.out.println(response.getBody());
return response.getBody();
}
}
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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
# 4.获取音频url
如果使用http协议,且想要获取用户录音结果,则可以根据响应请求结果中的header进行拼接音频url,获取音频。
一个正常的http请求,在返回结果的header中有session-id字段,例如:
session-id →sh:1542272221203805792:02055555-f4cd-4fef-8ed8-1a2089056acf
其中,sh是代表地域名称area,1542272221203805792是代表createtime;02055555-f4cd-4fef-8ed8-1a2089056acf 是代表请求中传入的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}
响应结果
{
"version": "full 1.0",
"score": 88.66,
"EvalType": "general",
"lines": [
{
"sample": "smart",
"usertext": "smart",
"begin": 0,
"end": 1.321,
"score": 88.66,
"fluency": 91.868,
"integrity": 100,
"pronunciation": 88.561,
"words": [
{
"StressOfWord": 1,
"phonetic": "smɑːt",
"text": "smart",
"type": 2,
"begin": 0.411,
"end": 1.301,
"volume": 7.479,
"score": 8.995,
"subwords": [
{
"subtext": "s",
"volume": 7.397,
"begin": 0.411,
"end": 0.541,
"score": 8.355
},
{
"subtext": "m",
"volume": 9,
"begin": 0.541,
"end": 0.681,
"score": 9.798
},
{
"subtext": "ɑː",
"volume": 6.492,
"begin": 0.681,
"end": 0.921,
"score": 9.425
},
{
"subtext": "t",
"volume": 7.025,
"begin": 0.921,
"end": 1.301,
"score": 8.937
}
]
}
]
}
]
}
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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
名称 | 类型 | 说明 |
---|---|---|
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代表该项检测正常 |
# 三、HTTP备份流程
备份流程主要是用于提高评测成功率,凡是使用HTTP方式接入评测,都建议使用备份流程。
备注:服务端未设置超时时间,客户端每步的超时时间算式为:
a.如果文本 <=10 个单词,设置为 3 秒;
b.如果文本 >10 个单词,设置为 3 + (n-10)/5 秒;