# 一、接口说明

把语音(≤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

# 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

# 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

# 5、结束识别

客户端发送结束识别请求,通知服务端语音数据发送结束,停止语音识别,服务端返回最终识别结果,格式详情参考返回结果示例

# 5.1、请求参数说明

参数 类型 描述 是否为空 可选值
type string 请求的阶段 NO end

# 5.2、请求参数示例

{
	"type": "end"
}
1
2
3

说明

当使用智能断句收到(server_vad=true)时,客户端无需发送结束识别请求

# 七、错误码

错误码 说明 解决方法
0 正确
20201 参数错误 客户端检查参数是否正确
20202 超过10s没有上传语音 检查客户端代码
20203 服务资源不足 建议重试,或者提工单,工单详情请提供sid
20204 服务内部错误 建议重试,或者提工单,工单详情请提供sid
20205 音频长度超过1分钟 检查音频文件是否过长
20206 并发超过限制 减小并发或者购买并发套餐
20207 套餐次数使用完 购买次数套餐
20208 appkey不存在 检查appkey是否合法
20209 客户端ip不在白名单中 检查是否开启白名单,同时检查客户端出口ip是否在ip白名单中