语音评测 API 文档
接口说明
语音评测（普通版）已下线，请老用户尽快迁移至语音评测（流式版），两者差异与迁移请参考常见问题
另外，原WebAPI语音评测（普通版），服务量与流式版不通用，如需续费或将服务量迁移至新版，请提交工单进行申请。
语音评测（普通版）接口通过智能语音技术自动对发音水平进行评价，包括：中文普通话发音水平自动评测技术、英文发音水平自动评测技术。请注意不支持自由说模式，需指定试题文本。试题格式，请点击 试题格式 查看详情。
该接口是通过HTTP API的方式给开发者提供一个通用的接口，适用于一次性交互数据传输的AI服务场景，即将音频一次性发送至云端，块式传输。相较于SDK，API具有轻量、跨语言的特点，不过请注意该接口使用的HTTP API协议不支持跨域。
接口Demo
示例demo 请点击 这里 下载。
目前仅提供部分开发语言的demo，其他语言请参照下方接口文档进行开发。
也欢迎热心的开发者到 讯飞开放平台社区 分享你们的demo。
接口要求
集成语音评测API时，需按照以下要求。
| 内容 | 说明 |
|---|---|
| 请求协议 | http[s] (为提高安全性，强烈推荐https) |
| 请求地址 | http[s]: //api.xfyun.cn/v1/service/v1/ise 注：服务器IP不固定，为保证您的接口稳定，请勿通过指定IP的方式调用接口，使用域名方式调用 |
| 请求方式 | POST |
| 接口鉴权 | 签名机制，见授权认证 |
| 字符编码 | UTF-8 |
| 响应格式 | 统一采用JSON格式 |
| 开发语言 | 任意，只要可以向讯飞云服务发起HTTP请求的均可 |
| 适用范围 | 任意操作系统，但因不支持跨域不适用于浏览器，请在后端调用接口 |
| 音频属性 | 采样率16k、位长16bit、单声道 |
| 音频格式 | PCM、WAV、SPEEX，样例音频可点击 这里 下载 |
| 音频大小 | 音频数据按要求编码(base64编码后进行urlencode)后大小不超过5M（WAV格式约2分钟） |
| 语言种类 | 中文普通话、英文 |
| 试题类型 | 字、词、句、篇章，试题格式请点击 试题格式 查看详情 |
接口调用流程
注： 若需配置IP白名单，请前往控制台。IP白名单规则请参照 IP白名单。
- 通过接口密钥基于MD5计算签名，将签名以及其他参数放在Http Request Header中，详见下方 请求头 。
- 将音频数据及试题文本数据放在Http Request Body中，以POST表单的形式提交，详见下方 请求体 。
- 向服务器端发送Http请求后，接收服务器端的返回结果，返回结果详见各接口的详细说明。
接口地址示例：
POST http[s]://api.xfyun.cn/v1/service/v1/ise HTTP/1.1
Content-Type:application/x-www-form-urlencoded; charset=utf-8
白名单
在调用该业务接口时
- 若关闭IP白名单，接口认为IP不限，不会校验IP。
- 若打开IP白名单，则服务端会检查调用方IP是否在讯飞开放平台配置的IP白名单中，对于没有配置到白名单中的IP发来的请求，服务端会拒绝服务。
IP白名单规则
- IP白名单，在 控制台-我的应用-相应服务的应用管理卡片上 编辑，保存后五分钟左右生效；
- 不同Appid的不同服务都需要分别设置IP白名单；
- IP白名单需设置为外网IP，请勿设置局域网IP；
- 如果服务器返回结果如下所示(illegal client_ip)，则表示由于未配置IP白名单或配置有误，服务端拒绝服务。
{
"code":"10105",
"desc":"illegal access|illegal client_ip",
"data":"",
"sid":"xxxxxx"
}
接口请求参数
请求头
在 Http Request Header 中配置以下参数。
授权认证
以下参数用于授权认证：
| 参数 | 格式 | 说明 | 必须 |
|---|---|---|---|
| X-Appid | string | 讯飞开放平台注册申请应用的应用ID(appid) | 是 |
| X-CurTime | string | 当前UTC时间戳 从1970年1月1日0点0 分0 秒开始到现在的秒数 | 是 |
| X-Param | string | 相关参数JSON串经Base64编码后的字符串，详见业务参数 | 是 |
| X-CheckSum | string | 令牌，计算方法：MD5(APIKey + X-CurTime + X-Param)，三个值拼接的字符串，进行MD5哈希计算（32位小写） | 是 |
注：
- APIKey：接口密钥，在讯飞开放平台控制台添加相应服务后即可获取，调用方注意保管，如泄露，可到控制台提交工单联系技术人员重置；
- X-CheckSum 有效期：出于安全性考虑，每个 X-CheckSum 的有效期为 5 分钟(用 X-CurTime 计算)，同时 X-CurTime 要与标准时间同步，否则时间相差太大，服务端会直接认为 X-CurTime 无效；
- BASE64 编码采用 MIME 格式，字符包括大小写字母各26个，加上10个数字，和加号 + ，斜杠 / ，一共64个字符。
*X-CheckSum *生成示例：
String APIKey="abcd1234";
String X-CurTime="1502607694";
String X-Param="eyAiYXVmIjogImF1ZGlvL0wxNjtyYXR...";
String X-CheckSum=MD5(apiKey + X-CurTime + X-Param);
业务参数
X-Param 为各配置参数组成的 JSON 串经 BASE64 编码之后的字符串，原始 JSON 串各字段说明如下：
| 参数 | 类型 | 必须 | 说明 | 示例 |
|---|---|---|---|---|
| aue | string | 是 | 音频编码 raw（未压缩的 pcm 格式音频） speex（标准开源speex） | raw |
| speex_size | string | 否 | 标准speex解码帧的大小 当aue=speex时，若传此参数，表明音频格式为标准speex 解码帧大小请参考这里； | 70 |
| result_level | string | 否 | 评测结果等级 entirety（默认值） simple | entirety |
| language | string | 是 | 评测语种 en_us（英语） zh_cn（汉语） | zh_cn |
| category | string | 是 | 评测题型 read_syllable（单字朗读，汉语专有） read_word（词语朗读） read_sentence（句子朗读） read_chapter(篇章朗读) | read_sentence |
| extra_ability | string | 否 | 拓展能力 multi_dimension(全维度 ) | multi_dimension |
注： 请注意使用speex格式的话，压缩前的原始音频文件，必须为采样率16K、16bits、单声道的PCM或WAV格式。且压缩后的音频与原版PCM音频因音频质量不同评分可能会略有不同，推荐使用pcm格式
X-Param生成示例：
原始JSON串：
{
"aue": "raw",
"result_level": "simple",
"language": "en_us",
"category": "read_sentence"
}
BASE64编码（即X-Param）：
eyJhdWUiOiAicmF3IiwicmVzdWx0X2xldmVsIjogInNpbXBsZSIsImxhbmd1YWdlIjogImVuX3VzIiwiY2F0ZWdvcnkiOiAicmVhZF9zZW50ZW5jZSJ9
请求体
以POST表单的形式提交以下参数：
| 参数 | 类型 | 必须 | 说明 | 示例 |
|---|---|---|---|---|
| audio | string | 是 | 音频数据 base64 编码后进行 urlencode 要求 base64 编码和 urlencode 后大小不超过5M | exSI6ICJl...... |
| text | string | 是 | 评测文本（使用 utf-8 编码）需urlencode 要求长度中文不超过180字节、英文不超过300字节，其格式详见 试题格式 | 天气很好。 |
注：
1）一般基础类库会默认进行urlencode处理，请注意不要重复处理
2）音频数据 base64 编码后大小会增加约1/3
接口返回参数
返回值为 json 串，各字段如下：
| 参数 | 类型 | 说明 |
|---|---|---|
| code | string | 结果码(具体见SDK&API错误码查询) |
| data | string | 语音评测结果 |
| desc | string | 描述 |
| sid | string | 会话ID |
其中 sid 字段主要用于追查问题，如果出现问题，可以提供 sid 给讯飞技术人员帮助确认问题。
data 即评测结果，其格式及字段含义详见 语音评测结果说明 文档。
示例如下：
失败：
{
"code": "10106",
"desc": "invalid parameter|invalid X-Appid",
"data": "",
"sid": "wse0000bb3f@ch3d5c059d83b3477200"
}
成功：
{
"data":{
"read_word":{
"lan":"en",
"type":"study",
"version":"6.5.0.1011",
"rec_paper":{
"read_word":{
"except_info":"28680",
"is_rejected":"false",
"total_score":"64.725080",
"sentence":[
{
"beg_pos":"0",
"content":"apple",
"end_pos":"129",
"word":{
"beg_pos":"79",
"content":"apple",
"end_pos":"129",
"total_score":"94.963020"
}
},
{
"beg_pos":"129",
"content":"banana",
"end_pos":"163",
"word":{
"beg_pos":"163",
"content":"banana",
"end_pos":"163",
"total_score":"0.000000"
}
},
{
"beg_pos":"163",
"content":"orange",
"end_pos":"226",
"word":{
"beg_pos":"163",
"content":"orange",
"end_pos":"226",
"total_score":"99.212200"
}
},
{
"content":"banana",
"end_pos":"359",
"word":{
"beg_pos":"265",
"content":"banana",
"end_pos":"318"
},
"beg_pos":"226"
}
],
"beg_pos":"0",
"content":"apple banana orange",
"end_pos":"359"
}
}
}
},
"code":"0",
"desc":"success",
"sid":"wse00000001@ll36940e324c59000100"
}
全维度说明
使用方法：extra_ability = multi_dimension
使用说明：使用全维度权限前后可获得的结果对比如下，红色为使用全维度以后才会返回的评分维度，返回结果各字段的详细说明请点击 语音评测结果说明 查看。
| 题型 | 中文 默认 | 中文 使用全维度 | 英文 默认 | 英文 使用全维度 |
|---|---|---|---|---|
| 字 | 总分(total_score) | 总分(total_score) 声韵分(phone_score) 调型分(tone_score) | - | - |
| 词 | 总分(total_score) | 总分(total_score) 声韵分(phone_score) 调型分(tone_score) | 总分(total_score) 音节得分(syll_score) | 总分(total_score) 音节得分(syll_score) 准确度分(accuracy_score) |
| 句 | 总分(total_score) | 总分(total_score) 完整度分(integrity_score) 流畅度分(fluency_score) 声韵分(phone_score) 调型分(tone_score) | 总分(total_score) 音节得分(syll_score) | 总分(total_score) 音节得分(syll_score) 完整度分(integrity_score) 流畅度分(fluency_score) 准确度分(accuracy_score) |
| 篇章 | 总分(total_score) | 总分(total_score) 完整度分(integrity_score) 流畅度分(fluency_score) 声韵分(phone_score) 调型分(tone_score) | 总分(total_score) 音节得分(syll_score) | 总分(total_score) 音节得分(syll_score) 完整度分(integrity_score) 流畅度分(fluency_score) 准确度分(accuracy_score) |
注：
中文声韵分：指声母和韵母正确率的得分。
中文调型分：指声调正确率的得分。
speex编码
语音评测支持speex编码压缩音频文件大小。请注意压缩前的原始音频文件，必须为采样率16K、16bits、单声道的PCM或WAV格式。
接口支持开源speex编码（需额外传speex_size参数，即解码帧大小），speex编解码，需下载编译speex库。详情可参考：https://www.speex.org/
speex_size与speex压缩等级的关系如下：
| 标准开源speex（压缩等级） | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 16k采样率 | 10 | 15 | 20 | 25 | 32 | 42 | 52 | 60 | 70 | 86 | 106 |
调用示例
注： 运行demo返回的结果中的 data 即评测结果，其格式及字段含义详见 语音评测结果说明
试题及音频样例
视频教程
常见问题
语音评测的APIKey在哪里查询到？
答：点击控制台--我的应用，找到对应应用的语音评测服务，即能查看到。
语音评测WebAPI支持多少路并发？
答：支持并发的，50路
语音评测支持题型和结果格式及字段含义？
答：评测试题需要符合一定的格式，汉语试题和英语试题有所不同，同语种的不同题型也有差异。
英文口语评测：支持单词，句子，篇章等题型评测。
中文口语评测：支持字、词、句，篇章等题型评测。
评测试题和结果格式及字段含义详见 语音评测试题格式及结果说明 文档。
语音评测最多支持多长时间的语音输入？
答：对于所有评测题型，都支持2min左右的音频语音输入。
语音评测支持传入的音频格式有哪些？
答：PCM、WAV、SPEEX，样例音频可点击 这里 下载。推荐使用Cool edit软件查询音频格式是否符合，音频格式不符合会检测为乱读，分值不能作为参考
错误码及相应解决方案查询网址
在这篇文章中：