更新说明
| 版本 |
更新时间 |
更新内容 |
| v1.0 |
2025-08-12 |
初始版本 |
| v1.1 |
2025-08-18 |
修改“创建声纹特征”、“修改声纹特征”支持的音频编码格式
删减“特征比对1:1”接口group_id参数 |
主动注册式声纹检索服务，使用API-KEY鉴权。
请求HOST：
https://api.listenai.com/
请求鉴权:
Authorization: Bearer {YOUR-API-KEY}
POST /v1/vpr/group
| 参数 |
类型 |
描述 |
必填 |
备注 |
| name |
string |
特征库名称 |
是 |
长度1-64字符 |
| info |
string |
特征库描述 |
否 |
长度不超过500字符 |
curl --location 'https://api.listenai.com/v1/vpr/group' \
--header 'Authorization: Bearer ${YOUR-API-KEY}' \
--header 'Content-Type: application/json' \
--data '{
"name": "测试声纹库001",
"info": "用于测试的声纹特征库"
}'
成功响应
{
"code": "SUCCESS",
"message": "创建成功",
"data": {
"id": "abc123def456",
"name": "测试声纹库001",
"info": "用于测试的声纹特征库",
"created_at": "2025-01-01T10:00:00+08:00",
"user_id": "user123"
}
}
DELETE /v1/vpr/group/:id
| 参数 |
类型 |
描述 |
必填 |
备注 |
| id |
string |
特征库 ID |
是 |
param 参数 |
| 参数 |
类型 |
说明 |
| code |
string |
状态码 |
| message |
string |
响应消息 |
curl --location --request DELETE 'https://api.listenai.com/v1/vpr/group/abc123def456' \
--header 'Authorization: Bearer ${YOUR-API-KEY}'
成功响应 - 200
{
"code": "SUCCESS",
"message": "删除成功"
}
PUT /v1/vpr/group/:id
| 参数 |
类型 |
描述 |
必填 |
备注 |
| name |
string |
特征库名称 |
否 |
长度1-64字符 |
| info |
string |
特征库描述 |
否 |
长度不超过500字符 |
| 参数 |
类型 |
说明 |
| code |
string |
状态码 |
| message |
string |
响应消息 |
curl --location --request PUT 'https://api.listenai.com/v1/vpr/group/abc123def456' \
--header 'Authorization: Bearer ${YOUR-API-KEY}' \
--header 'Content-Type: application/json' \
--data '{
"name": "更新后的特征库名称",
"info": "更新后的特征库描述"
}'
成功响应 - 200
{
"code": "SUCCESS",
"message": "更新成功"
}
GET /v1/vpr/group/:id
| 参数 |
类型 |
描述 |
必填 |
备注 |
| id |
string |
特征库 ID |
是 |
param 参数 |
curl --location 'https://api.listenai.com/v1/vpr/group/abc123def456' \
--header 'Authorization: Bearer ${YOUR-API-KEY}'
成功响应 - 200
{
"code": "SUCCESS",
"message": "查询成功",
"data": {
"id": "abc123def456",
"name": "测试声纹库001",
"info": "用于测试的声纹特征库",
"created_at": "2025-01-01T10:00:00+08:00",
"user_id": "user123"
}
}
GET /v1/vpr/groups?page&pageSize
| 参数 |
类型 |
描述 |
必填 |
备注 |
| page |
number |
页码 |
是 |
从1开始 |
| pageSize |
number |
每页数量 |
是 |
1-100之间 |
| 参数 |
类型 |
说明 |
| code |
string |
状态码 |
| message |
string |
响应消息 |
| page |
number |
当前页码 |
| pageSize |
number |
每页数量 |
| total |
number |
总数量 |
| data |
Array<VprGroupObject> |
声纹特征库列表 |
curl --location 'https://api.listenai.com/v1/vpr/groups?page=1&pageSize=10' \
--header 'Authorization: Bearer ${YOUR-API-KEY}'
成功响应 - 200
{
"code": "SUCCESS",
"message": "查询成功",
"page": 1,
"pageSize": 10,
"total": 2,
"data": [
{
"id": "abc123def456",
"name": "测试声纹库001",
"info": "用于测试的声纹特征库",
"created_at": "2025-01-01T10:00:00+08:00",
"user_id": "user123"
},
{
"id": "def456ghi789",
"name": "员工声纹库",
"info": "用于识别员工的声纹特征库",
"created_at": "2025-01-02T10:00:00+08:00",
"user_id": "user123"
}
]
}
POST /v1/vpr/feature
| 参数 |
类型 |
描述 |
必填 |
备注 |
| group_id |
string |
特征库ID |
是 |
所属声纹特征库ID |
| name |
string |
特征名称 |
是 |
长度1-64字符 |
| info |
string |
特征描述 |
否 |
长度不超过500字符 |
| audio |
object |
音频对象 |
是 |
音频相关信息 |
| audio.text |
string |
音频文本 |
否 |
长度不超过500字符 |
| audio.audio_data |
string |
音频数据 |
是 |
base64编码的音频数据 |
| audio.encoding |
string |
编码格式 |
否 |
lame/speex/speex-wb |
| audio.channels |
number |
声道数 |
否 |
1或2，默认1 |
| audio.sample_rate |
number |
采样率 |
否 |
固定16000，默认16000 |
| audio.bit_depth |
number |
位深 |
否 |
固定16，默认16 |
audio.encoding参数取值说明
| 取值 |
描述 |
| lame |
MP3编码格式，兼容性最好，文件大小适中 |
| speex |
开源语音编码格式，适合语音压缩 |
| speex-wb |
宽带Speex编码，支持更高频率范围 |
curl --location 'https://api.listenai.com/v1/vpr/feature' \
--header 'Authorization: Bearer ${YOUR-API-KEY}' \
--header 'Content-Type: application/json' \
--data '{
"group_id": "abc123def456",
"name": "张三声纹",
"info": "张三的声纹特征",
"audio": {
"text": "这是张三的语音样本",
"audio_data": "UklGRnoGAABXQVZFZm10IBAAAAABAAEAQB8AAEAfAAABAAgAZGF0YQoGAACBhYqFbF1fdJivrJBhNjVgodDbq2EcBj+a2/LDciUFLIHO8tiJNwgZaLvt559NEAxQp+PwtmMcBjiR1/LMeSwFJHfH8N2QQAoUXrTp66hVFApGn+DyvmwhBSuBzvLZiTYIG2m98OScTgwOUarm7blmGgU7k9n1unEiBC13yO/eizEIHWq+8+OWT...",
"encoding": "lame",
"channels": 1,
"sample_rate": 16000,
"bit_depth": 16
}
}'
成功响应
{
"code": "SUCCESS",
"message": "创建成功",
"data": {
"id": "feature123",
"name": "张三声纹",
"info": "张三的声纹特征",
"audio": {
"text": "这是张三的语音样本",
"encoding": "lame",
"channels": 1,
"sample_rate": 16000,
"bit_depth": 16,
"audio_md5": "abc123def456"
},
"created_at": "2025-01-01T10:00:00+08:00",
"group_id": "abc123def456",
"user_id": "user123"
}
}
失败响应
{
"error": "检测到 3 个说话人，无法处理"
}
DELETE /v1/vpr/feature/:id
| 参数 |
类型 |
描述 |
必填 |
备注 |
| id |
string |
特征 ID |
是 |
param 参数 |
| 参数 |
类型 |
说明 |
| code |
string |
状态码 |
| message |
string |
响应消息 |
curl --location --request DELETE 'https://api.listenai.com/v1/vpr/feature/feature123' \
--header 'Authorization: Bearer ${YOUR-API-KEY}'
成功响应 - 200
{
"code": "SUCCESS",
"message": "删除成功"
}
PUT /v1/vpr/feature/:id
| 参数 |
类型 |
描述 |
必填 |
备注 |
| name |
string |
特征名称 |
否 |
长度1-64字符 |
| info |
string |
特征描述 |
否 |
长度不超过500字符 |
| audio |
object |
音频对象 |
否 |
音频相关信息 |
| audio.text |
string |
音频文本 |
否 |
长度不超过500字符 |
| audio.audio_data |
string |
音频数据 |
否 |
base64编码的音频数据 |
| audio.encoding |
string |
编码格式 |
否 |
lame/speex/speex-wb |
| audio.channels |
number |
声道数 |
否 |
1或2，默认1 |
| audio.sample_rate |
number |
采样率 |
否 |
固定16000，默认16000 |
| audio.bit_depth |
number |
位深 |
否 |
固定16，默认16 |
| 参数 |
类型 |
说明 |
| code |
string |
状态码 |
| message |
string |
响应消息 |
curl --location --request PUT 'https://api.listenai.com/v1/vpr/feature/feature123' \
--header 'Authorization: Bearer ${YOUR-API-KEY}' \
--header 'Content-Type: application/json' \
--data '{
"name": "更新后的特征名称",
"info": "更新后的特征描述",
"audio": {
"text": "更新后的音频文本",
"audio_data": "UklGRnoGAABXQVZFZm10IBAAAAABAAEAQB8AAEAfAAABAAgAZGF0YQoGAACBhYqFbF1fdJivrJBhNjVgodDbq2EcBj+a2/LDciUFLIHO8tiJNwgZaLvt559NEAxQp+PwtmMcBjiR1/LMeSwFJHfH8N2QQAoUXrTp66hVFApGn+DyvmwhBSuBzvLZiTYIG2m98OScTgwOUarm7blmGgU7k9n1unEiBC13yO/eizEIHWq+8+OWT...",
"encoding": "lame",
"channels": 1,
"sample_rate": 16000,
"bit_depth": 16
}
}'
成功响应 - 200
{
"code": "SUCCESS",
"message": "更新成功"
}
GET /v1/vpr/feature/:id
| 参数 |
类型 |
描述 |
必填 |
备注 |
| id |
string |
特征 ID |
是 |
param 参数 |
curl --location 'https://api.listenai.com/v1/vpr/feature/feature123' \
--header 'Authorization: Bearer ${YOUR-API-KEY}'
成功响应 - 200
{
"code": "SUCCESS",
"message": "查询成功",
"data": {
"id": "feature123",
"name": "张三声纹",
"info": "张三的声纹特征",
"audio": {
"text": "这是张三的语音样本",
"encoding": "lame",
"channels": 1,
"sample_rate": 16000,
"bit_depth": 16,
"audio_md5": "abc123def456"
},
"created_at": "2025-01-01T10:00:00+08:00",
"group_id": "abc123def456",
"user_id": "user123"
}
}
GET /v1/vpr/features?group_id&page&pageSize
| 参数 |
类型 |
描述 |
必填 |
备注 |
| group_id |
string |
特征库ID |
否 |
按特征库筛选 |
| page |
number |
页码 |
否 |
从1开始，默认1 |
| pageSize |
number |
每页数量 |
否 |
1-100之间，默认10 |
| 参数 |
类型 |
说明 |
| code |
string |
状态码 |
| message |
string |
响应消息 |
| page |
number |
当前页码 |
| pageSize |
number |
每页数量 |
| total |
number |
总数量 |
| data |
Array<VprFeatureObject> |
声纹特征列表 |
curl --location 'https://api.listenai.com/v1/vpr/features?group_id=abc123def456&page=1&pageSize=10' \
--header 'Authorization: Bearer ${YOUR-API-KEY}'
成功响应 - 200
{
"code": "SUCCESS",
"message": "查询成功",
"page": 1,
"pageSize": 10,
"total": 2,
"data": [
{
"id": "feature123",
"name": "张三声纹",
"info": "张三的声纹特征",
"audio": {
"text": "这是张三的语音样本",
"encoding": "lame",
"channels": 1,
"sample_rate": 16000,
"bit_depth": 16,
"audio_md5": "abc123def456"
},
"created_at": "2025-01-01T10:00:00+08:00",
"group_id": "abc123def456",
"user_id": "user123"
},
{
"id": "feature456",
"name": "李四声纹",
"info": "李四的声纹特征",
"audio": {
"text": "这是李四的语音样本",
"encoding": "lame",
"channels": 1,
"sample_rate": 16000,
"bit_depth": 16,
"audio_md5": "def456ghi789"
},
"created_at": "2025-01-02T10:00:00+08:00",
"group_id": "abc123def456",
"user_id": "user123"
}
]
}
POST /v1/vpr/feature/compare
| 参数 |
类型 |
描述 |
必填 |
备注 |
group_id |
string |
特征库ID |
是 |
1.1版本弃用 |
| feature_id |
string |
特征ID |
是 |
要比对的声纹特征ID |
| audio |
object |
音频对象 |
是 |
要比对的音频信息 |
| audio.text |
string |
音频文本 |
否 |
长度不超过500字符 |
| audio.audio_data |
string |
音频数据 |
是 |
base64编码的音频数据 |
| audio.encoding |
string |
编码格式 |
否 |
lame/speex/speex-wb |
| audio.channels |
number |
声道数 |
否 |
1或2，默认1 |
| audio.sample_rate |
number |
采样率 |
否 |
固定16000，默认16000 |
| audio.bit_depth |
number |
位深 |
否 |
固定16，默认16 |
curl --location 'https://api.listenai.com/v1/vpr/feature/compare' \
--header 'Authorization: Bearer ${YOUR-API-KEY}' \
--header 'Content-Type: application/json' \
--data '{
"feature_id": "feature123",
"audio": {
"text": "这是要比对的语音",
"audio_data": "UklGRnoGAABXQVZFZm10IBAAAAABAAEAQB8AAEAfAAABAAgAZGF0YQoGAACBhYqFbF1fdJivrJBhNjVgodDbq2EcBj+a2/LDciUFLIHO8tiJNwgZaLvt559NEAxQp+PwtmMcBjiR1/LMeSwFJHfH8N2QQAoUXrTp66hVFApGn+DyvmwhBSuBzvLZiTYIG2m98OScTgwOUarm7blmGgU7k9n1unEiBC13yO/eizEIHWq+8+OWT...",
"encoding": "lame",
"channels": 1,
"sample_rate": 16000,
"bit_depth": 16
}
}'
成功响应
{
"code": "SUCCESS",
"message": "比对成功",
"data": {
"group_id": "abc123def456",
"feature_id": "feature123",
"feature_info": "张三的声纹特征",
"gender": "male",
"age": "25-35",
"score": 0.95,
"user_id": "user123"
}
}
POST /v1/vpr/group/compare
| 参数 |
类型 |
描述 |
必填 |
备注 |
| group_id |
string |
特征库ID |
是 |
要比对的声纹特征库ID |
| top_k |
number |
返回数量 |
否 |
返回前K个最匹配结果，1-10，默认3 |
| audio |
object |
音频对象 |
是 |
要比对的音频信息 |
| audio.audio_data |
string |
音频数据 |
是 |
base64编码的音频数据 |
| audio.encoding |
string |
编码格式 |
否 |
lame/speex/speex-wb |
| audio.channels |
number |
声道数 |
否 |
1或2，默认1 |
| audio.sample_rate |
number |
采样率 |
否 |
固定16000，默认16000 |
| audio.bit_depth |
number |
位深 |
否 |
固定16，默认16 |
curl --location 'https://api.listenai.com/v1/vpr/group/compare' \
--header 'Authorization: Bearer ${YOUR-API-KEY}' \
--header 'Content-Type: application/json' \
--data '{
"group_id": "abc123def456",
"top_k": 5,
"audio": {
"audio_data": "UklGRnoGAABXQVZFZm10IBAAAAABAAEAQB8AAEAfAAABAAgAZGF0YQoGAACBhYqFbF1fdJivrJBhNjVgodDbq2EcBj+a2/LDciUFLIHO8tiJNwgZaLvt559NEAxQp+PwtmMcBjiR1/LMeSwFJHfH8N2QQAoUXrTp66hVFApGn+DyvmwhBSuBzvLZiTYIG2m98OScTgwOUarm7blmGgU7k9n1unEiBC13yO/eizEIHWq+8+OWT...",
"encoding": "lame",
"channels": 1,
"sample_rate": 16000,
"bit_depth": 16
}
}'
成功响应
{
"code": "SUCCESS",
"message": "比对成功",
"data": {
"group_id": "abc123def456",
"scoreList": [
{
"featureId": "feature123",
"featureInfo": "张三的声纹特征",
"score": 0.95
},
{
"featureId": "feature456",
"featureInfo": "李四的声纹特征",
"score": 0.87
},
{
"featureId": "feature789",
"featureInfo": "王五的声纹特征",
"score": 0.76
}
],
"gender": "male",
"age": "25-35",
"user_id": "user123"
}
}
用于声纹识别任务的音频数据格式定义
在声纹识别中，音频质量直接影响识别准确率，平台对音频格式有严格要求：
- 采样率：固定16000Hz，这是语音识别的最佳采样率
- 位深：固定16bit，提供足够的动态范围
- 声道数：支持1声道（单声道）或2声道（立体声），推荐使用单声道
- 编码格式：支持多种格式，各有优势
编码格式对比
| 格式 |
优势 |
适用场景 |
| lame |
兼容性最好，文件大小适中 |
通用场景，兼容性要求高 |
| speex |
开源格式，语音压缩效率高 |
语音通信，带宽受限 |
| speex-wb |
宽带支持，开源免费 |
开源项目，宽带语音 |
音频质量建议
音频时长：建议在3-10秒之间，过短可能信息不足，过长会增加处理时间
音频清晰度：避免噪音、回声等干扰，确保语音清晰
音量适中：避免过小或过大，建议在-20dB到-3dB之间
采样一致性：同一人的多个样本应保持相同的采样参数
API接口返回对象定义
| 参数 |
类型 |
说明 |
| id |
string |
特征库ID |
| name |
string |
特征库名称 |
| info |
string |
特征库描述 |
| created_at |
string |
创建时间 |
| user_id |
string |
用户ID |
| 参数 |
类型 |
说明 |
| id |
string |
特征ID |
| name |
string |
特征名称 |
| info |
string |
特征描述 |
| audio |
object |
音频信息 |
| created_at |
string |
创建时间 |
| group_id |
string |
特征库ID |
| user_id |
string |
用户ID |
| 参数 |
类型 |
说明 |
| text |
string |
音频文本 |
| encoding |
string |
编码格式 |
| channels |
number |
声道数 |
| sample_rate |
number |
采样率 |
| bit_depth |
number |
位深 |
| audio_md5 |
string |
音频MD5值 |
| 参数 |
类型 |
说明 |
| group_id |
string |
特征库ID |
| feature_id |
string |
特征ID |
| feature_info |
string |
特征描述 |
| gender |
string |
性别 |
| age |
string |
年龄范围 |
| score |
number |
匹配分数 |
| user_id |
string |
用户ID |
| 参数 |
类型 |
说明 |
| group_id |
string |
特征库ID |
| scoreList |
Array<VprScoreItemObject> |
分数列表 |
| gender |
string |
性别 |
| age |
string |
年龄范围 |
| user_id |
string |
用户ID |
| 参数 |
类型 |
说明 |
| featureId |
string |
特征ID |
| featureInfo |
string |
特征描述 |
| score |
number |
匹配分数 |
| 错误码 |
HTTP状态码 |
说明 |
| SUCCESS |
200 |
成功 |
| BAD_REQUEST |
400 |
请求参数错误 |
| NOT_FOUND |
404 |
资源不存在 |
| INTERNAL_SERVER_ERROR |
500 |
服务器内部错误 |