语音识别|ai平台|ai开放平台-云知声声纹识别

一、接口说明
二、接口Demo
三、接口要求
四、接口调用流程
五、错误码
六、常见问题

# 一、接口说明

声纹识别（Voice-print Recognize），是一项提取说话人声音特征和说话内容信息，自动核验说话人身份的技术。

 调用过程中涉及步骤如下：
    1.创建声纹组 (必须)
    2.在组内创建声纹 (必须)
    3.声纹确认【1:1】 (必须)
    4.声纹辨认【1:N】 (必须)
    5.修改声纹 (非必须)
    6.删除声纹 (非必须)
    7.删除声纹组 (非必须)
    8.查询组内声纹列表 (非必须)

声纹确认【1:1】和声纹辨认【1:N】根据使用场景二选一即可。

# 二、接口Demo

Java示例demo (opens new window)
python3示例demo (opens new window)
js示例demo (opens new window)

# 三、接口要求

集成声纹识别API时，需按照以下要求：

内容	说明
请求协议	http[s] （为提高安全性，强烈推荐https）
请求方式	POST
请求地址	http[s]: //ai-vpr.hivoice.cn
接口鉴权	签名机制，详情请参照下方接口鉴权
字符编码	UTF-8
响应格式	统一采用JSON格式
开发语言	任意，只要可以向服务发起发起HTTP请求的均可
操作系统	任意
音频属性	采样率16K、单声道
音频格式	pcm, mp3, opus
声纹长度	音频数据BASE64编码（编码后最小长度:1B 最大长度:4M）

# 四、接口调用流程

• 通过接口密钥基于SHA256计算签名，将签名以及其他参数加在请求Body中。详见下方 接口鉴权 。
• 将请求参数以及BASE64数据放在Http Request Body中，以POST形式提交，详见下方 请求参数 。
• 向服务器端发送HTTP请求后，接收服务器端的返回结果。

# 1、接口鉴权

创建声纹组、删除声纹组、创建声纹、修改声纹、查询组内声纹列表、删除声纹、声纹确认[1:1]、声纹辨认[1:N]接口都需要进行鉴权

# 1.1、鉴权方法

参数	描述	示例
appkey	用户的appkey	***
timestamp	访问时间戳,UNIX时间戳（毫秒数）	1585047674022
sign	签名	***
nonce	随机数，每次访问都需要改变，建议使用UUID	b5e3df4fb29140de8ee4df1f8f6f5543

A）将上述参数按照appkey、timestamp、secret secret查询 (opens new window)、nonce 顺序拼接字符串；
B）将A形成字符串获取SHA256摘要，形成一个64位的十六进制（字母大写）字符串，即为本次请求sign（签名）的值

# 1.2、鉴权示例代码

/**
 * Sha256 摘要加密
 *
 * @param data
 * @return
 */
public static String getSHA256(String data) {
    String digest = null;
    try {
        MessageDigest md = MessageDigest.getInstance("SHA-256");
        byte[] bytes = md.digest(data.getBytes(StandardCharsets.UTF_8));
        digest = byte2hex(bytes);
    } catch (Exception e) {
        log.error("No support algorithm!", e);
    }
    return digest;
}

/**
 * 二进制转十六进制字符串
 *
 * @param bytes
 * @return
 */
private static String byte2hex(byte[] bytes) {
    StringBuilder sign = new StringBuilder();
    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());
    }
    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
25
26
27
28
29
30
31
32
33
34
35

# 2、创建声纹组

声纹组内可存储多个声纹，便于业务管理声纹。

协议	URL	方法
HTTP/HTTPS	http://ai-vpr.hivoice.cn/vpr/v1/createGroup	POST

# 2.1、参数说明

参数名	类型	是否必输	描述
appkey	string	是	应用Key
timestamp	integer	是	访问时间戳,UNIX时间戳（毫秒数）
nonce	string	是	随机数，每次访问都需要改变，建议使用UUID
sign	string	是	签名
groupId	string	是	声纹组ID,可自定义，建议使用UUID
groupInfo	string	是	声纹组信息

# 2.2、请求参数示例

{
  "appkey": "cio3sbla7padsttovnsut76ex7mopmxxfd4icxao",
  "timestamp": 1585047674022,
  "nonce": "0187434d5f0b46468eeed4bfb4cc32ff",
  "sign": "F81C83E9BFD04C6FEFBA411CDA360024666AF3E1E7E1EFFB69C07D50BDBAC5C2",
  "groupId": "vpr-demo-group-id",
  "groupInfo": "我的声纹组信息描述"
}

1
2
3
4
5
6
7
8

# 2.3、响应结果

参数名称	参数说明	类型
code	错误码	integer
msg	消息	string
sid	会话唯一标识	string
data	结果体JSON	object

data属性说明

参数名称	参数说明	类型
groupId	声纹组ID	string
groupInfo	声纹组信息	string

# 2.4、响应结果示例

{
	"code": 0,
	"msg": "",
	"sid": "",
	"data": {
		"groupId": "",
		"groupInfo": ""
	}
}

1
2
3
4
5
6
7
8
9

# 3、创建声纹

协议	URL	方法
HTTP/HTTPS	http://ai-vpr.hivoice.cn/vpr/v1/createFeature	POST

# 3.1、参数说明

参数名称	参数说明	是否必输	数据类型
appkey	appkey	是	string
timestamp	访问时间戳,UNIX时间戳（毫秒数）	是	integer
nonce	随机数，每次访问都需要改变，建议使用UUID	是	string
sign	签名	是	string
groupId	声纹组ID	是	string
featureId	声纹ID[可自定义，建议UUID,不能超过128位]	否	string
featureInfo	声纹描述	是	string
audioData	音频数据BASE64编码（编码后最小长度:1B 最大长度:4M）	是	string
audioSampleRate	采样率 16000	是	integer
audioFormat	音频格式 pcm、mp3、opus	是	string

# 3.2、请求参数示例

{
	"appkey": "cio3sbla7padsttovnsut76ex7mopmxxfd4icxao",
	"timestamp": 1585047674022,
	"nonce": "0187434d5f0b46468eeed4bfb4cc32ff",
	"sign": "F81C83E9BFD04C6FEFBA411CDA360024666AF3E1E7E1EFFB69C07D50BDBAC5C2",
	"groupId": "vpr-demo-group-id",
	"featureId": "vpr-demo-feature-id",
	"featureInfo": "创建声纹描述信息",
	"audioData": "",
	"audioSampleRate": 16000,
	"audioFormat": "mp3"
}

1
2
3
4
5
6
7
8
9
10
11
12

# 3.3、响应结果

参数名称	参数说明	类型
code	错误码	integer
msg	消息	string
sid	会话唯一标识	string
data	返回结果体JSON	object

data属性说明

参数名称	参数说明	类型
featureId	声纹ID	string
featureInfo	声纹信息	string

# 3.4、响应结果示例

{
  "code": 0,
  "msg": "",
  "sid": "",
  "data": {
    "featureId": "",
    "featureInfo": ""
  }
}

1
2
3
4
5
6
7
8
9

# 4、声纹确认 [1:1]

通过一个音频和一个已注册的声纹做对比。

协议	URL	方法
HTTP/HTTPS	http://ai-vpr.hivoice.cn/vpr/v1/confirmFeature	POST

# 4.1、参数说明

参数名称	参数说明	是否必输	数据类型
appkey	appkey	是	string
timestamp	访问时间戳,UNIX时间戳（毫秒数）	是	integer
nonce	随机数，每次访问都需要改变，建议使用UUID	是	string
sign	签名	是	string
groupId	声纹组ID	是	string
featureId	声纹ID	是	string
audioData	音频数据BASE64编码（编码后最小长度:1B 最大长度:4M）	是	string
audioSampleRate	采样率 16000	是	integer
audioFormat	音频格式 pcm、mp3、opus	是	string

# 4.2、请求参数示例

{
	"appkey": "cio3sbla7padsttovnsut76ex7mopmxxfd4icxao",
	"timestamp": 1585047674022,
	"nonce": "0187434d5f0b46468eeed4bfb4cc32ff",
	"sign": "F81C83E9BFD04C6FEFBA411CDA360024666AF3E1E7E1EFFB69C07D50BDBAC5C2",
	"groupId": "vpr-demo-group-id",
	"featureId": "vpr-demo-feature-id",
	"audioData": "",
	"audioSampleRate": 16000,
	"audioFormat": "mp3"
}

1
2
3
4
5
6
7
8
9
10
11

# 4.3、响应结果

参数名称	参数说明	类型
code	错误码	integer
msg	消息	string
sid	会话唯一标识	string
data	结果体JSON	object

data属性说明

参数名称	参数说明	类型
score	分数，0表示未匹配	number
featureId	声纹ID	string
featureInfo	声纹信息	string

# 4.4、响应结果示例

{
  "code": 0,
  "msg": "",
  "sid": "",
  "data": {
    "score": 0,
    "featureId": "",
    "featureInfo": ""
  }
}

1
2
3
4
5
6
7
8
9
10

# 5、声纹辨认 [1:N]

# 5.1 通过一个音频和一个声纹组内的多个已注册的声纹做对比。

协议	URL	方法
HTTP/HTTPS	http://ai-vpr.hivoice.cn/vpr/v1/identifyFeatureByGroupId	POST

# 5.1.1、参数说明

参数名称	参数说明	是否必输	数据类型
appkey	appkey	是	string
timestamp	访问时间戳,UNIX时间戳（毫秒数）	是	integer
nonce	随机数，每次访问都需要改变，建议使用UUID	是	string
sign	签名	是	string
groupId	声纹组ID	是	string
topN	返回前几条，最小1 最大10	是	integer
audioData	音频数据BASE64编码（编码后最小长度:1B 最大长度:4M）	是	string
audioSampleRate	采样率 16000	是	integer
audioFormat	音频格式 pcm、mp3、opus	是	string

# 5.1.2、请求参数示例

{
	"appkey": "cio3sbla7padsttovnsut76ex7mopmxxfd4icxao",
	"timestamp": 1585047674022,
	"nonce": "0187434d5f0b46468eeed4bfb4cc32ff",
	"sign": "F81C83E9BFD04C6FEFBA411CDA360024666AF3E1E7E1EFFB69C07D50BDBAC5C2",
	"groupId": "vpr-demo-group-id",
	"topN": 0,
	"audioData": "",
	"audioSampleRate": 16000,
	"audioFormat": "mp3"
}

1
2
3
4
5
6
7
8
9
10
11

# 5.1.3、响应结果

参数名称	参数说明	类型
code	错误码	integer
msg	消息	string
sid	会话唯一标识	string
data	返回结果体JSON	object

data属性说明

参数名称	参数说明	类型
score	分数，0表示未匹配	number
featureId	声纹ID	string
featureInfo	声纹信息	string

# 5.1.4、响应结果示例

{
  "code": 0,
  "msg": "",
  "sid": "",
  "data": [
    {
      "score": 0,
      "featureId": "",
      "featureInfo": ""
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12

# 5.2 通过一个音频和多个已注册的声纹做对比，提供不同组内的多个声纹id。

协议	URL	方法
HTTP/HTTPS	http://ai-vpr.hivoice.cn/vpr/v1/identifyFeatureByIds	POST

# 5.2.1、参数说明

参数名称	参数说明	是否必输	数据类型
appkey	appkey	是	string
timestamp	访问时间戳,UNIX时间戳（毫秒数）	是	integer
nonce	随机数，每次访问都需要改变，建议使用UUID	是	string
sign	签名	是	string
featureList	声纹ID组	是	array
topN	返回前几条，最小1 最大10	是	integer
audioData	音频数据BASE64编码（编码后最小长度:1B 最大长度:4M）	是	string
audioSampleRate	采样率 16000	是	integer
audioFormat	音频格式 pcm、mp3、opus	是	string

featureList数组属性说明

参数名称	参数说明	是否必输	数据类型
groupId	声纹组ID	是	string
featureId	声纹ID	是	string

# 5.2.2、请求参数示例

{
	"appkey": "cio3sbla7padsttovnsut76ex7mopmxxfd4icxao",
	"timestamp": 1585047674022,
	"nonce": "0187434d5f0b46468eeed4bfb4cc32ff",
	"sign": "F81C83E9BFD04C6FEFBA411CDA360024666AF3E1E7E1EFFB69C07D50BDBAC5C2",
	"featureList": [
		{
			"groupId": "vpr-demo-group-id",
			"featureId": "vpr-demo-feature-id"
		}
	],
	"topN": 0,
	"audioData": "",
	"audioSampleRate": 16000,
	"audioFormat": "mp3"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 5.2.3、响应结果

参数名称	参数说明	类型
code	错误码	integer(int32)
msg	消息	string
sid	会话唯一标识	string
data	返回结果体JSON	array

data属性说明

参数名称	参数说明	类型
score	分数，0表示未匹配	number
featureId	声纹ID	string
featureInfo	声纹信息	string

# 5.2.4、响应结果示例

{
  "code": 0,
  "msg": "",
  "sid": "",
  "data": [
    {
      "score": 0,
      "featureId": "",
      "featureInfo": ""
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12

# 6、修改声纹

协议	URL	方法
HTTP/HTTPS	http://ai-vpr.hivoice.cn/vpr/v1/updateFeatureById	POST

# 6.1、参数说明

参数名称	参数说明	是否必输	数据类型
appkey	appkey	是	string
timestamp	访问时间戳,UNIX时间戳（毫秒数）	是	integer
nonce	随机数，每次访问都需要改变，建议使用UUID	是	string
sign	签名	是	string
groupId	声纹组id	是	string
featureId	声纹id	是	string
featureInfo	声纹描述	否	string
audioData	音频数据BASE64编码（编码后最小长度:1B 最大长度:4M）	是	string
audioSampleRate	采样率 16000	是	integer
audioFormat	音频格式 pcm、mp3、opus	是	string

# 6.2、请求参数示例

{
	"appkey": "cio3sbla7padsttovnsut76ex7mopmxxfd4icxao",
	"timestamp": 1585047674022,
	"nonce": "0187434d5f0b46468eeed4bfb4cc32ff",
	"sign": "F81C83E9BFD04C6FEFBA411CDA360024666AF3E1E7E1EFFB69C07D50BDBAC5C2",
	"groupId": "vpr-demo-group-id",
	"featureId": "vpr-demo-feature-id",
	"featureInfo": "修改声纹的信息描述",
	"audioData": "",
	"audioSampleRate": 16000,
	"audioFormat": "mp3"
}

1
2
3
4
5
6
7
8
9
10
11
12

# 6.3、响应结果

参数名称	参数说明	类型
code	错误码	integer
msg	消息	string
sid	会话唯一标识	string
data	返回结果体JSON	object

data属性说明

参数名称	参数说明	类型
result	true更新成功，false更新失败	boolean

# 6.4、响应结果示例

{
  "code": 0,
  "msg": "",
  "sid": "",
  "data": {
    "result": true
  }
}

1
2
3
4
5
6
7
8

# 7、删除声纹

协议	URL	方法
HTTP/HTTPS	http://ai-vpr.hivoice.cn/vpr/v1/delFeatureById	POST

# 7.1、参数说明

参数名称	参数说明	是否必输	数据类型
appkey	appkey	是	string
timestamp	访问时间戳,UNIX时间戳（毫秒数）	是	integer
nonce	随机数，每次访问都需要改变，建议使用UUID	是	string
sign	签名	是	string
groupId	声纹组信息	是	string
featureId	声纹ID	是	string

# 7.2、请求参数示例

{
	"appkey": "cio3sbla7padsttovnsut76ex7mopmxxfd4icxao",
	"timestamp": 1585047674022,
	"nonce": "0187434d5f0b46468eeed4bfb4cc32ff",
	"sign": "F81C83E9BFD04C6FEFBA411CDA360024666AF3E1E7E1EFFB69C07D50BDBAC5C2",
	"groupId": "vpr-demo-group-id",
	"featureId": "vpr-demo-feature-id"
}

1
2
3
4
5
6
7
8

# 7.3、响应结果

参数名称	参数说明	类型
code	错误码	integer
msg	消息	string
sid	会话唯一标识	string
data	结果体JSON	object

data属性说明

参数名称	参数说明	类型
result	true删除成功，false删除失败	boolean

# 7.4、响应结果示例

{
  "code": 0,
  "msg": "",
  "sid": "",
  "data": {
    "result": true
  }
}

1
2
3
4
5
6
7
8

# 8、删除声纹组

协议	URL	方法
HTTP/HTTPS	http://ai-vpr.hivoice.cn/vpr/v1/delGroupById	POST

# 8.1、参数说明

参数名称	参数说明	是否必输	数据类型
appkey	appkey	是	string
timestamp	访问时间戳,UNIX时间戳（毫秒数）	是	integer
nonce	随机数，每次访问都需要改变，建议使用UUID	是	string
sign	签名	是	string
groupId	声纹组信息	是	string

# 8.2、请求参数示例

{
	"appkey": "cio3sbla7padsttovnsut76ex7mopmxxfd4icxao",
	"timestamp": 1585047674022,
	"nonce": "0187434d5f0b46468eeed4bfb4cc32ff",
	"sign": "F81C83E9BFD04C6FEFBA411CDA360024666AF3E1E7E1EFFB69C07D50BDBAC5C2",
	"groupId": "vpr-demo-group-id"
}

1
2
3
4
5
6
7

# 8.3、响应结果

参数名称	参数说明	类型
code	错误码	integer
msg	消息	string
sid	会话唯一标识	string
data	结果体JSON	object

data属性说明

参数名称	参数说明	类型
result	true删除成功，false删除失败	boolean

# 8.4、响应结果示例

{
  "code": 0,
  "msg": "",
  "sid": "",
  "data": {
    "result": true
  }
}

1
2
3
4
5
6
7
8

# 9、查询组内声纹列表

协议	URL	方法
HTTP/HTTPS	http://ai-vpr.hivoice.cn/vpr/v1/findFeatureListByGroupId	POST

# 9.1、参数说明

参数名称	参数说明	是否必输	数据类型
appkey	appkey	是	string
timestamp	访问时间戳,UNIX时间戳（毫秒数）	是	integer
nonce	随机数，每次访问都需要改变，建议使用UUID	是	string
sign	签名	是	string
groupId	声纹组ID	是	string

# 9.2、请求参数示例

{
	"appkey": "cio3sbla7padsttovnsut76ex7mopmxxfd4icxao",
	"timestamp": 1585047674022,
	"nonce": "0187434d5f0b46468eeed4bfb4cc32ff",
	"sign": "F81C83E9BFD04C6FEFBA411CDA360024666AF3E1E7E1EFFB69C07D50BDBAC5C2",
	"groupId": "vpr-demo-group-id"
}

1
2
3
4
5
6
7

# 9.3、响应结果

参数名称	参数说明	类型
code	错误码	integer
msg	消息	string
sid	会话唯一标识	string
data	结果体JSON	array

data属性说明

参数名称	参数说明	类型
featureId	声纹ID	string
featureInfo	声纹信息	string

# 9.4、响应结果示例

{
  "code": 0,
  "msg": "",
  "sid": "",
  "data": [
    {
      "featureId": "",
      "featureInfo": ""
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11

# 五、错误码

错误码	说明	解决办法
0	正常	成功
100100	服务内部错误	建议重试，或者提工单，工单详情请提供groupId
100101	参数错误	客户端检查参数是否正确
100102	请求非法	检查调用方式或参数
100103	签名校验失败	参考接口鉴权中示例，检查签名
100104	appkey不存在	检查appkey是否合法
100105	重放攻击	检查是否重复调用
100106	时间戳与当前时间偏差较大	检查时间戳字段
100107	groupId已存在	重复创建groupId
100108	插入group失败	检查声纹信息是否合规
100109	groupId错误	groupId不存在,或者提工单，工单详情请提供groupId
100110	featureId已存在	重复创建featureId
100111	插入feature失败	检查声纹信息是否合规
100112	featureId不存在	请创建声纹
100113	组内没有声纹	请根据groupId查询组内是否存在声纹
100114	服务内部错误	请提工单
100115	注册失败或注册结果为空	服务器内部错误,请提工单
100116	featureId没有声纹结果	请查询当前组内是否存在此声纹
100117	音频文件类型不支持	请检查是否是支持的音频格式
100118	采样率仅支持16000	请参考接口要求
100121	套餐次数使用完	请购买套餐

声纹识别1:1与1:N有什么区别?

答：1:1模式主要做身份验证，主要证明你是你，主要应用场景为实名制场景（例如声纹解锁、声纹支付等）。而1:N模式则是验证你是谁，应用场景有办公考勤、会议签到等。

声纹的识别是否需要读固定的文本，文本有什么限制?

答：不需要读固定的文本，文本没有限制。

声纹识别得分在什么范围可以判定验证通过?

答：建议的参考得分范围为60-100可以判定验证通过，具体可以结合应用场景的安全性要求做进一步判断。

不同appkey可以创建名称相同的声纹特征库吗?

答：可以，每个appkey的声纹特征库是相互独立的。

← 口语评测FAQ WebAPI文档 →