# 一、接口说明

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

# 二、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

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

# 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
名称 类型 说明
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方式接入评测，都建议使用备份流程。 avatar
备注：服务端未设置超时时间，客户端每步的超时时间算式为：
a.如果文本 <=10 个单词，设置为 3 秒；
b.如果文本 >10 个单词，设置为 3 + (n-10)/5 秒；

# 四、错误码

错误码查询 (opens new window)

← Android SDK文档 →