AI 助理
文档备案控制台
官方文档
首页 智能语音交互 用户指南 语音分析 说话人识别 接口说明

接口说明

更新时间：
复制 MD 格式
产品详情
我的收藏

说话人识别将说话人读出的连续数字串语音与指定说话人的已注册声纹进行1:1比对。当比对结果满足阈值条件时，身份验证通过。

计费和并发限制

说话人识别提供试用版和商用版，详情请参见服务版本说明。升级操作请参见升级为商用版。

计费方式请参见计费说明；并发限制请参见并发和QPS。

使用限制

  • 音频编码格式为PCM，采样位数为16 bit，单声道，采样率为16000 Hz。

  • 注册、更新和认证的音频长度均不得超过30秒。

  • 获取的数字串有效期为2分钟。

  • 说话人ID（speaker_id）长度不超过32字节。

  • 说话人识别用于通过朗读指定数字串进行身份认证，不适用于在多人对话中识别不同说话人。

服务地址

访问方式

说明

URL

外网访问

所有服务器均可使用。SDK默认使用该地址，无需另行设置。

wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1

VPC内网访问

适用于华东2（上海）地域的ECS实例，须通过VPC访问。经典网络不支持通过内网访问语音服务。

ws://nls-gateway-cn-shanghai-internal.aliyuncs.com:80/ws/v1
说明

通过内网访问不会产生ECS实例的公网流量费用。

交互流程

客户端通过WebSocket发送JSON指令，并接收服务端的JSON事件。每次操作使用一个任务ID，后续指令沿用该任务ID。Java SDK接入示例请参见说话人识别Java SDK。

鉴权

建立WebSocket连接时使用Token鉴权。获取方法请参见获取Token。

获取数字串（ApplyDigit）

发送StartTask，将action设为ApplyDigit并指定speaker_id。收到TaskStarted后发送StopTask，从TaskResult的payload.digit获取数字串。该操作不发送音频。

image

声音注册（Enroll）

先获取数字串，再发送StartTask，将action设为Enroll。收到TaskStarted后发送朗读该数字串的音频；音频发送完毕后发送StopTask，等待TaskResult确认注册结果。

指定speaker_id的声纹记录已存在时，不能重复注册。更新已有声纹使用Update；需要重新注册时，先使用Delete删除已有记录。

image

声音更新（Update）

先获取数字串，再发送StartTask，将action设为Update。收到TaskStarted后发送朗读该数字串的音频；音频发送完毕后发送StopTask，等待TaskResult确认更新结果。

image

声音认证（Verify）

先获取数字串，再发送StartTask，将action设为Verify。收到TaskStarted后发送朗读该数字串的音频；音频发送完毕后发送StopTask，从TaskResult获取认证结果。

image

声音删除（Delete）

发送StartTask，将action设为Delete并指定speaker_id。收到TaskStarted后发送StopTask，等待TaskResult确认删除结果。该操作不发送音频。

image

请求说明

在智能语音交互控制台获取项目的Appkey，替换报文中的<Appkey>。以下报文中的speaker_id、任务ID和数字串仅为示例值，调用时使用实际值。

请求header参数

参数名称

参数类型

参数说明

namespace

String

固定为SpeakerVerification。

name

String

请求指令：StartTask启动任务，StopTask结束任务。

appkey

String

项目的Appkey。

task_id

String

客户端生成的任务全局唯一ID。在StartTask中指定，后续StopTask沿用相同值。

message_id

String

本次消息的ID。

启动任务（StartTask）

获取数字串 (ApplyDigit)

参数名称

参数类型

参数说明

action

String

固定为ApplyDigit。

speaker_id

String

必填，说话人ID，长度不超过32字节。

 
{
    "header": {
        "message_id": "fedcba9876543210fedcba9876543210",
        "task_id": "0123456789abcdef0123456789abcdef",
        "namespace": "SpeakerVerification",
        "name": "StartTask",
        "appkey": "<Appkey>"
    },
    "payload": {
        "action": "ApplyDigit",
        "speaker_id": "test_speaker"
    }
}

声音注册 (Enroll)

参数名称

参数类型

参数说明

action

String

固定为Enroll。

format

String

必填，音频编码格式，固定为pcm。

sample_rate

Integer

必填，采样率，固定为16000，单位为Hz。

speaker_id

String

必填，说话人ID，长度不超过32字节。

digit

String

必填，通过ApplyDigit获取的数字串。

 
{
    "header": {
        "message_id": "fedcba9876543210fedcba9876543210",
        "task_id": "0123456789abcdef0123456789abcdef",
        "namespace": "SpeakerVerification",
        "name": "StartTask",
        "appkey": "<Appkey>"
    },
    "payload": {
        "action": "Enroll",
        "format": "pcm",
        "sample_rate": 16000,
        "speaker_id": "test_speaker",
        "digit": "04587236"
    }
}

声音更新 (Update)

参数名称

参数类型

参数说明

action

String

固定为Update。

format

String

必填，音频编码格式，固定为pcm。

sample_rate

Integer

必填，采样率，固定为16000，单位为Hz。

speaker_id

String

必填，说话人ID，长度不超过32字节。

digit

String

必填，通过ApplyDigit获取的数字串。

 
{
    "header": {
        "message_id": "fedcba9876543210fedcba9876543210",
        "task_id": "0123456789abcdef0123456789abcdef",
        "namespace": "SpeakerVerification",
        "name": "StartTask",
        "appkey": "<Appkey>"
    },
    "payload": {
        "action": "Update",
        "format": "pcm",
        "sample_rate": 16000,
        "speaker_id": "test_speaker",
        "digit": "04587236"
    }
}

声音认证 (Verify)

参数名称

参数类型

参数说明

action

String

固定为Verify。

format

String

必填，音频编码格式，固定为pcm。

sample_rate

Integer

必填，采样率，固定为16000，单位为Hz。

speaker_id

String

必填，说话人ID，长度不超过32字节。

digit

String

必填，通过ApplyDigit获取的数字串。

 
{
    "header": {
        "message_id": "fedcba9876543210fedcba9876543210",
        "task_id": "0123456789abcdef0123456789abcdef",
        "namespace": "SpeakerVerification",
        "name": "StartTask",
        "appkey": "<Appkey>"
    },
    "payload": {
        "action": "Verify",
        "format": "pcm",
        "sample_rate": 16000,
        "speaker_id": "test_speaker",
        "digit": "04587236"
    }
}

声音删除 (Delete)

参数名称

参数类型

参数说明

action

String

固定为Delete。

speaker_id

String

必填，说话人ID，长度不超过32字节。

 
{
    "header": {
        "message_id": "fedcba9876543210fedcba9876543210",
        "task_id": "0123456789abcdef0123456789abcdef",
        "namespace": "SpeakerVerification",
        "name": "StartTask",
        "appkey": "<Appkey>"
    },
    "payload": {
        "action": "Delete",
        "speaker_id": "test_speaker"
    }
}

结束任务（StopTask）

五类操作均使用StopTask结束任务。获取数字串和删除声音时，在收到TaskStarted后发送；注册、更新和认证时，在音频发送完毕后发送。结束任务后等待TaskResult，不要用关闭连接代替结束指令。

参数名称

参数类型

参数说明

task_id

String

与客户端StartTask请求中的任务ID相同。

 
{
    "header": {
        "message_id": "fedcba9876543210fedcba9876543211",
        "task_id": "0123456789abcdef0123456789abcdef",
        "namespace": "SpeakerVerification",
        "name": "StopTask",
        "appkey": "<Appkey>"
    },
    "payload": {}
}

响应说明

响应header参数

参数名称

参数类型

参数说明

namespace

String

固定为SpeakerVerification。

name

String

响应事件：TaskStarted表示任务已启动，TaskResult携带任务结果，TaskFailed表示任务失败。

status

Integer

服务状态码。20000000表示成功；错误码请参见服务状态码。

status_text

String

状态消息。

task_id

String

与客户端请求中的任务ID相同，可用于定位任务。

message_id

String

本次消息的ID。

任务启动事件（TaskStarted）

TaskStarted用于确认任务已启动，不包含最终结果。

{
    "header": {
        "message_id": "fedcba9876543210fedcba9876543210",
        "task_id": "0123456789abcdef0123456789abcdef",
        "namespace": "SpeakerVerification",
        "name": "TaskStarted",
        "status": 20000000,
        "status_text": "Gateway:SUCCESS:Success."
    },
    "payload": {}
}

任务结果事件（TaskResult）

获取数字串 (ApplyDigit)

参数名称

参数类型

参数说明

user_id

String

阿里云账号ID。

appkey

String

项目的Appkey。

speaker_id

String

说话人ID。

digit

String

8位数字串。

 
{
    "header": {
        "message_id": "fedcba9876543210fedcba9876543210",
        "task_id": "0123456789abcdef0123456789abcdef",
        "namespace": "SpeakerVerification",
        "name": "TaskResult",
        "status": 20000000,
        "status_text": "Gateway:SUCCESS:Success."
    },
    "payload": {
        "user_id": "123456",
        "appkey": "<Appkey>",
        "speaker_id": "test_speaker",
        "digit": "04587236"
    }
}

声音注册 (Enroll)

参数名称

参数类型

参数说明

user_id

String

阿里云账号ID。

appkey

String

项目的Appkey。

speaker_id

String

说话人ID。

digit

String

本次操作使用的数字串。

 
{
    "header": {
        "message_id": "fedcba9876543210fedcba9876543210",
        "task_id": "0123456789abcdef0123456789abcdef",
        "namespace": "SpeakerVerification",
        "name": "TaskResult",
        "status": 20000000,
        "status_text": "Gateway:SUCCESS:Success."
    },
    "payload": {
        "user_id": "123456",
        "appkey": "<Appkey>",
        "speaker_id": "test_speaker",
        "digit": "04587236"
    }
}

声音更新 (Update)

参数名称

参数类型

参数说明

user_id

String

阿里云账号ID。

appkey

String

项目的Appkey。

speaker_id

String

说话人ID。

digit

String

本次操作使用的数字串。

 
{
    "header": {
        "message_id": "fedcba9876543210fedcba9876543210",
        "task_id": "0123456789abcdef0123456789abcdef",
        "namespace": "SpeakerVerification",
        "name": "TaskResult",
        "status": 20000000,
        "status_text": "Gateway:SUCCESS:Success."
    },
    "payload": {
        "user_id": "123456",
        "appkey": "<Appkey>",
        "speaker_id": "test_speaker",
        "digit": "04587236"
    }
}

声音认证 (Verify)

参数名称

参数类型

参数说明

user_id

String

阿里云账号ID。

appkey

String

项目的Appkey。

speaker_id

String

说话人ID。

digit

String

本次操作使用的数字串。

score

String

置信度，取值范围为[0.0,100.0]，值越大表示置信度越高。

decision

Integer

认证结果：1表示通过，0表示未通过。

 
{
    "header": {
        "message_id": "fedcba9876543210fedcba9876543210",
        "task_id": "0123456789abcdef0123456789abcdef",
        "namespace": "SpeakerVerification",
        "name": "TaskResult",
        "status": 20000000,
        "status_text": "Gateway:SUCCESS:Success."
    },
    "payload": {
        "user_id": "123456",
        "appkey": "<Appkey>",
        "speaker_id": "test_speaker",
        "digit": "04587236",
        "score": "100.0",
        "decision": 1
    }
}

声音删除 (Delete)

参数名称

参数类型

参数说明

user_id

String

阿里云账号ID。

appkey

String

项目的Appkey。

speaker_id

String

说话人ID。

 
{
    "header": {
        "message_id": "fedcba9876543210fedcba9876543210",
        "task_id": "0123456789abcdef0123456789abcdef",
        "namespace": "SpeakerVerification",
        "name": "TaskResult",
        "status": 20000000,
        "status_text": "Gateway:SUCCESS:Success."
    },
    "payload": {
        "user_id": "123456",
        "appkey": "<Appkey>",
        "speaker_id": "test_speaker"
    }
}

服务状态码

服务响应的header.status包含服务状态码。发生错误时，结合status_text检查原因并处理。

通用错误码

错误码

原因

解决办法

40000001

身份认证失败

检查Token是否正确或已过期。

40000002

无效的消息

检查消息是否符合协议要求。

40000010

新用户3个月免费试用期已结束

继续使用需升级为商用版，操作请参见升级为商用版。

40000004

空闲超时

检查是否连续10秒未向服务端发送数据。

40000005

请求数量过多

检查是否超过并发连接数或QPS限制。超过并发数时，可升级为商用版或扩容商用版并发资源。

41010120

客户端超时

客户端连续10秒及以上未发送数据。检查音频发送情况。

40000000

客户端错误

根据错误消息检查请求。返回Gateway:CLIENT_ERROR:vpr profile is exist!时，指定speaker_id的声纹记录已存在。更新已有声纹使用Update；重新注册先使用Delete删除已有记录；注册另一条记录使用新的speaker_id。

50000000

服务端错误

内部服务错误，重试请求。

50000001

内部调用错误

内部服务错误，重试请求。

52010001

内部调用错误

内部服务错误，重试请求。

网关错误码

错误码

原因

解决办法

40010001

不支持的接口

升级至最新SDK。

40010002

不支持的指令

升级至最新SDK。

40010003

无效的指令

升级至最新SDK。

40010004

客户端提前断开连接

检查是否在请求正常完成前关闭连接。

40010005

任务状态错误

检查是否发送了当前任务状态不能处理的指令。

配置错误码

错误码

原因

解决办法

40020105

应用不存在

解析路由时找不到应用，检查Appkey。

40020106

Appkey与Token不匹配

检查Appkey是否正确，是否与Token属于同一账号。

40020503

RAM用户鉴权失败

使用阿里云账号为调用接口的RAM用户授予POP API访问权限。
上一篇：说话人识别下一篇：Java SDK