- ···
- 产品服务
- ···
- 解决方案
- ···
- 文档中心
- ···
# 一、接口说明
把语音(≤60秒)转换成对应的文字信息,适用于较短的语音交互场景,如语音搜索、语音输入、语音控制等。
# 二、接口Demo
Java示例demo (opens new window)
python3示例demo (opens new window)
js示例demo (opens new window)
# 三、接口要求
集成一句话识别流式API时,需按照以下要求:
内容 | 说明 |
---|---|
请求协议 | ws[s](为提高安全性,强烈推荐wss) |
请求地址 | 中文普通话:ws[s]: //ws-osasr.hivoice.cn/v1/asr 方言、英语:ws[s]: //ws-osasr-dialect.hivoice.cn/v1/asr 注:服务器IP不固定,为保证您的接口稳定,请勿通过指定IP的方式调用接口,使用域名方式调用 |
接口鉴权 | 签名机制,详情请参照下方接口鉴权 |
字符编码 | UTF-8 |
响应格式 | 统一采用JSON格式 |
开发语言 | 任意,只要可以向服务发起Websocket请求的均可 |
操作系统 | 任意 |
音频属性 | 采样率16k或8K、位长16bit、单声道 |
音频格式 | pcm、opus、adpcm、speex、amr |
音频长度 | 最长60s |
语言种类 | 中文普通话、英语、粤语、四川话 |
# 四、IP白名单
默认关闭IP白名单,即该服务不限制调用IP。 在调用该业务接口时
- 若关闭IP白名单,接口认为IP不限,不会校验IP。
- 若打开IP白名单,则服务端会检查调用方IP是否在开放平台配置的IP白名单中,对于没有配置到白名单中的IP发来的请求,服务端会拒绝服务。
- 若打开IP白名单,同时没有设置任何IP,接口会认为此时没有设置白名单,所以打开IP白名单时,请务必设置IP,否则无法生效。
IP白名单规则
- 登录 云知声AI开放平台控制台 (opens new window)
- 选择应用的查看详情
- IP白名单处编辑,保存后五分钟左右生效。
- 不同appkey的不同服务都需要分别设置IP白名单。
- IP白名单需设置为外网IP,请勿设置局域网IP。
# 五、热词
一句话识别支持应用级个性化热词,具体设置方法参考设置热词
# 六、接口调用流程
- 通过接口密钥基于SHA256计算签名,向服务器端发送Websocket协议握手请求。详见接口鉴权。
- 握手成功后,客户端发送开始识别标记和识别参数,详见开始识别
- 客户端通过Websocket连接同时发送语音和接收识别结果。详见发送语音数据、接收识别结果
- 数据上传完毕,客户端需要发送结束标记,详见结束识别。
- 服务端返回全部结果后会主动断开Websocket连接
注: Websocket使用注意事项如下
- 服务端支持的Websocket-version 为13,请确保客户端使用的框架支持该版本。
- 服务端返回的所有的帧类型均为TextMessage,对应于原生Websocket的协议帧中opcode=1,请确保客户端解析到的帧类型一定为该类型,如果不是,请尝试升级客户端框架版本,或者更换技术框架。
- 如果出现分帧问题,即一个json数据包分多帧返回给了客户端,导致客户端解析json失败。出现这种问题大部分情况是客户端的框架对Websocket协议解析存在问题,如果出现请先尝试升级框架版本,或者更换技术框架。
- 客户端会话结束后如果需要关闭连接,尽量保证传给服务端的错误码为Websocket错误码1000(如果客户端框架没有提供关闭时传错误码的接口。则无需关注本条)。
# 1、接口鉴权
在握手阶段,请求方需要对请求进行签名,服务端通过签名来校验请求的合法性。
请求示例
ws[s]://ws-osasr.hivoice.cn/v1/asr?time=1585047674022&appkey=xxxxxxxxxxx&sign=xxxxxxxxxx
1
# 1.1、鉴权方法
参数 | 描述 | 示例 | 备注 |
---|---|---|---|
appkey | 用户的appkey | *** | 必需 |
time | 访问时间戳,Unix时间戳(毫秒数) | 1585047674022 | 必需 |
sign | 签名 | *** | 必需 |
A)将上述参数按照appkey、time、secret secret查询 (opens new window) 顺序拼接字符串;
B)将A形成字符串获取SHA256摘要,形成一个64位的十六进制(字母大写)字符串,即为本次请求sign(签名)的值
# 1.2、鉴权示例代码
/**
* 热词签名获取方法
* @param appkey
* @param timestamp
* @param secret
* @return
*/
public String getSign(String appkey, String timestamp, String secret) {
String originalStr = appkey + timestamp + secret;
StringBuilder sign = new StringBuilder();
try {
MessageDigest md = MessageDigest.getInstance("SHA-256");
byte[] bytes = md.digest(originalStr.getBytes(StandardCharsets.UTF_8));
for (int i = 0; i < bytes.length; i++) {
String hex = Integer.toHexString(bytes[i] & 0xFF);
if (hex.length() == 1) {
sign.append("0");
}
sign.append(hex.toUpperCase());
}
} catch (Exception unused) {
}
return sign.toString();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 1.3、鉴权结果
如果握手成功,会返回HTTP 101状态码,表示协议升级成功;
如果握手失败,则根据不同错误类型返回不同HTTP Code状态码,同时携带错误描述信息,
详细错误说明如下:
HTTP Code | 说明 | 解决方法 |
---|---|---|
401 | 签名校验失败 | 签名验证失败,可能原因有多种。 1. 检查appkey,signature 是否正确 2.检查计算签名的参数appkey,timestamp,secret是否按照协议要求拼接。 |
403 | 时钟偏移校验失败 | 检查服务器时间是否标准,相差5分钟以上会报此错误 |
# 2、开始识别
握手成功后客户端和服务端会建立Websocket连接,客户端通过Websocket文本传输发起一次识别。
# 2.1、参数说明
参数名 | 类型 | 必传 | 描述 | 可选值 | 默认值 |
---|---|---|---|---|---|
type | string | 是 | 请求的阶段 | start | |
domain | string | 否 | 领域,可设置多个,以英文逗号分隔,最多4个。设置多个领域将导致识别速度下降 | general(通用) movietv(影视) song(音乐) poi(地图) medical(医疗) eshopping(电商) home(家居) law(法律) childEdu(儿童教育) finance(金融) | general |
acoustic_setting | string | 否 | 声学模型,near 近讲,far 远讲 | near,far | near |
format | string | 否 | 语音编码格式 | opus,adpcm,speex,pcm,amr | pcm |
sample | string | 否 | 采样率 | 16k,8k | 16k |
lang | string | 否 | 语言 | cn(中文) en(英文) cantonese(粤语) sichuanese(四川话) | cn |
variable | string | 否 | 是否返回可变结果 | true,false | true |
punctuation | string | 否 | 是否开启标点符号添加 | true,false | true |
post_proc | string | 否 | 是否开启数字格式转为阿拉伯数字格式 | true,false | true |
server_vad | string | 否 | 是否开启智能断句 | true,false | false |
max_start_silence | string | 否 | 允许的最大开始静音时长,单位是毫秒,超出后服务端将会发送结束事件,结束本次识别,需要先设置server_vad为true。 | 正整数 | 2000 |
max_end_silence | string | 否 | 允许的最大结束静音时长,单位是毫秒,有效范围200~2000ms,超出时长服务端会发送结束事件,结束本次识别(需要注意的是后续的语音不会继续进行识别),需要先设置server_vad为true。 | 正整数 | 500 |
user_id | string | 否 | 用户标识 |
# 2.2、请求参数示例
{
"type": "start",
"data": {
"server_vad": "false",
"post_proc": "true",
"domain": "general",
"format": "pcm",
"variable": "true",
"punctuation": "true",
"acoustic_setting": "near",
"lang": "cn",
"sample": "16k",
"max_start_silence": "1000",
"user_id": "userid-001",
"max_end_silence": "500"
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 3、发送语音数据
通过Websocket发送二进制语音数据,建议每次发送音频间隔100ms
说明
整个会话时长最多持续60s,或者超过10s未发送数据,服务端会主动断开连接
# 4、接收识别结果
接收识别结果是通过Websocket的onMessage(String)方法
# 4.1、识别结果说明
参数 | 类型 | 描述 | 是否为空 |
---|---|---|---|
code | int | 错误码 | NO |
msg | string | 结果说明 | NO |
sid | string | 识别的唯一id | NO |
server_vad | boolean | 是否服务端智能断句 | NO |
end | boolean | 请求是否结束 | NO |
type | string | 结果类型:"variable":可变结果,"fixed":固定结果 | |
text | string | 识别结果 | NO |
说明
当end=true时,表示语音识别完成,此时将不再处理继续发送的语音数据,客户端应终止发送语音数据,若需要识别其他语音数据则需要重新start。
# 4.2、返回结果示例
{
"code": 0,
"end": false,
"msg": "success",
"server_vad": false,
"sid": "67165a9676dc4a818500545be0d9075a",
"text": "北京",
"type": "variable"
}
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
# 5、结束识别
客户端发送结束识别请求,通知服务端语音数据发送结束,停止语音识别,服务端返回最终识别结果,格式详情参考返回结果示例。
# 5.1、请求参数说明
参数 | 类型 | 描述 | 是否为空 | 可选值 |
---|---|---|---|---|
type | string | 请求的阶段 | NO | end |
# 5.2、请求参数示例
{
"type": "end"
}
1
2
3
2
3
说明
当使用智能断句收到(server_vad=true)时,客户端无需发送结束识别请求
# 七、错误码
错误码 | 说明 | 解决方法 |
---|---|---|
0 | 正确 | |
20201 | 参数错误 | 客户端检查参数是否正确 |
20202 | 超过10s没有上传语音 | 检查客户端代码 |
20203 | 服务资源不足 | 建议重试,或者提工单,工单详情请提供sid |
20204 | 服务内部错误 | 建议重试,或者提工单,工单详情请提供sid |
20205 | 音频长度超过1分钟 | 检查音频文件是否过长 |
20206 | 并发超过限制 | 减小并发或者购买并发套餐 |
20207 | 套餐次数使用完 | 购买次数套餐 |
20208 | appkey不存在 | 检查appkey是否合法 |
20209 | 客户端ip不在白名单中 | 检查是否开启白名单,同时检查客户端出口ip是否在ip白名单中 |