文档

接口说明

更新时间:

说话人识别功能可以将说话人所读出的连续数字串语音,与语音库中该用户ID所对应的声音特征进行1:1比对验证,当声音特征比对满足阈值条件时则身份验证成功。

使用须知

  • 支持的输入格式:PCM编码文件、16 bit采样位数、单声道(mono)。

  • 支持的音频采样率:16000 Hz。

服务地址

访问类型

说明

URL

外网访问

所有服务器均可使用外网访问URL(SDK中默认设置了外网访问URL,无需您设置)。

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

阿里云上海ECS内网访问

使用阿里云上海ECS(ECS地域为华东2(上海)),可使用内网访问URL。 ECS的经典网络不能访问AnyTunnel,即不能在内网访问语音服务;如果希望使用AnyTunnel,需要创建专有网络在其内部访问。

说明

  • 使用内网访问方式,将不会产生ECS实例的公网流量费用。

  • 关于ECS的网络类型请参见网络类型

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

交互流程

1. 鉴权

客户端在与服务端建立WebSocket连接时,使用Token进行鉴权。Token获取请参见获取Token

2. 获取数字串(ApplyDigit)

image

3. 声音注册(Enroll)

image

4. 声音更新(Update)

image

5. 声音认证(Verify)

image

6. 声音删除(Delete)

image

交互协议-请求

1. 获取数字串请求

获取声音数字串,数字串有效时长为2分钟。

参数名称

参数类型

参数说明

action

String

系统规定参数,取值:ApplyDigit。

speaker_id

String

可自定义说话人ID,必填(长度不超过32位字节)。

{
    "header": {
        "message_id": "05450bf69c53413f8d88aed1ee60****",
        "task_id": "640bc797bb684bd6960185651307****",
        "namespace": "SpeakerVerification",
        "name": "StartTask",
        "appkey": "17d4c634****"      //获取Appkey请前往控制台:https://nls-portal.console.aliyun.com/applist
    },
    "payload": {
        "action":"ApplyDigit",
        "speaker_id": "test_speaker"
    }
}

2. 声音注册请求

开始声音注册,注册的音频长度限制为30秒。

参数名称

参数类型

参数说明

action

String

系统规定参数,取值:Enroll。

format

String

音频编码格式,目前支持PCM,必填。

sample_rate

Integer

音频采样率,目前支持16000,单位:Hz,必填。

speaker_id

String

说话人ID,必填(长度不超过32位字节)。

digit

String

用户获取的数字串,必填。

{
    "header": {
        "message_id": "05450bf69c53413f8d88aed1ee60****",
        "task_id": "640bc797bb684bd6960185651307****",
        "namespace": "SpeakerVerification",
        "name": "StartTask",
        "appkey": "17d4c634****"      //获取Appkey请前往控制台:https://nls-portal.console.aliyun.com/applist
    },
    "payload": {
        "action": "Enroll",
        "format": "pcm",
        "sample_rate": 16000,
        "speaker_id": "test_speaker",
        "digit":"04587236"
    }
}

3. 声音更新请求

开始声音更新,更新的音频长度限制为30秒。

参数名称

参数类型

参数说明

action

String

系统规定参数,取值:Update。

format

String

音频编码格式,目前支持PCM,必填。

sample_rate

Integer

音频采样率,目前支持16000,必填。

speaker_id

String

说话人ID,必填(长度不超过32位字节)。

digit

String

用户获取的数字串,必填。

{
    "header": {
        "message_id": "05450bf69c53413f8d88aed1ee60****",
        "task_id": "640bc797bb684bd6960185651307****",
        "namespace": "SpeakerVerification",
         "name": "StartTask",
        "appkey": "17d4c634****"      //获取Appkey请前往控制台:https://nls-portal.console.aliyun.com/applist
    },
    "payload": {
        "action": "Update",
        "format": "pcm",
        "sample_rate": 16000,
        "speaker_id": "test_speaker",
        "digit":"04587236"
    }
}

4. 声音认证请求

开始声音认证,认证的音频长度限制为30秒。

参数名称

参数类型

参数说明

action

String

系统规定参数,取值:Verify。

format

String

音频编码格式,目前支持PCM,必填。

sample_rate

Integer

音频采样率,目前支持16000,必填。

speaker_id

String

说话人ID,必填(长度不超过32位字节)。

digit

String

用户获取的数字串,必填。

{
    "header": {
        "message_id": "05450bf69c53413f8d88aed1ee60****",
        "task_id": "640bc797bb684bd6960185651307****",
        "namespace": "SpeakerVerification",
        "name": "StartTask",
        "appkey": "17d4c634****"      //获取Appkey请前往控制台:https://nls-portal.console.aliyun.com/applist
    },
    "payload": {
        "action": "Verify",
        "format": "pcm",
        "sample_rate": 16000,
        "speaker_id": "test_speaker",
        "digit":"04587236"
    }
}

5. 删除声音请求

删除声音指令。

参数名称

参数类型

参数说明

action

String

系统规定参数,取值:Delete。

speaker_id

String

说话人ID,必填(长度不超过32位字节)。

{
    "header": {
        "message_id": "05450bf69c53413f8d88aed1ee60****",
        "task_id": "640bc797bb684bd6960185651307****",
        "namespace": "SpeakerVerification",
        "name": "StartTask",
        "appkey": "17d4c634****"      //获取Appkey请前往控制台:https://nls-portal.console.aliyun.com/applist
    },
    "payload": {
        "action": "Delete",
        "speaker_id": "test_speaker"
    }
}

交互协议-响应

1. 获取数字串响应

获取声音登录数字串信息。

参数名称

参数类型

参数说明

user_id

String

阿里云账号ID。

appkey

String

应用名。

获取Appkey请前往控制台

speaker_id

String

说话人ID。

digit

String

8位数字串。

{
    "header": {
        "message_id": "05450bf69c53413f8d88aed1ee60****",
        "task_id": "640bc797bb684bd6960185651307****",
        "namespace": "SpeakerVerification",
        "name": "TaskResult",
        "status": 20000000,
        "status_text": "Gateway:SUCCESS:Success."
    },
      "payload": {
        "user_id": "123456",
        "appkey": "17d4c634****",
        "speaker_id": "test_speaker",
        "digit": "04587236"
    }
}

2. 声音注册响应

声音注册结束。

参数名称

参数类型

参数说明

user_id

String

阿里云账号ID。

appkey

String

应用名。

获取Appkey请前往控制台

speaker_id

String

说话人ID。

digit

String

注册时的数字串信息。

{
    "header": {
        "message_id": "05450bf69c53413f8d88aed1ee60****",
        "task_id": "640bc797bb684bd6960185651307****",
        "namespace": "SpeakerVerification",
        "name": "TaskResult",
        "status": 20000000,
        "status_text": "Gateway:SUCCESS:Success."
    },
     "payload": {
      "user_id": "123456",
        "appkey": "17d4c634****",
        "speaker_id": "test_speaker",
        "digit": "04587236"
    }
}

3. 声音更新响应

声音更新完成。

参数名称

参数类型

参数说明

user_id

String

阿里云账号ID。

appkey

String

应用名。

获取Appkey请前往控制台

speaker_id

String

说话人ID。

digit

String

更新时的数字串信息。

{
    "header": {
        "message_id": "05450bf69c53413f8d88aed1ee60****",
        "task_id": "640bc797bb684bd6960185651307****",
        "namespace": "SpeakerVerification",
        "name": "TaskResult",
        "status": 20000000,
        "status_text": "Gateway:SUCCESS:Success."
    },
     "payload": {
      "user_id": "123456",
        "appkey": "17d4c634****",
        "speaker_id": "test_speaker",
        "digit": "04587236"
    }
}

4. 声音认证响应

声音认证完成。

参数名称

参数类型

参数说明

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": "05450bf69c53413f8d88aed1ee60****",
        "task_id": "640bc797bb684bd6960185651307****",
        "namespace": "SpeakerVerification",
        "name": "TaskResult",
        "status": 20000000,
        "status_message": "Gateway:SUCCESS:Success."
    },
     "payload": {
        "user_id": "123456",
        "appkey": "17d4c634****",
        "speaker_id": "test_speaker",
        "digit": "04587236",
        "score":"100.0",
        "decision":1
    }
}

5. 声音删除响应

声音删除完成。

参数名称

参数类型

参数说明

speaker_id

String

用户ID。

{
    "header": {
        "message_id": "05450bf69c53413f8d88aed1ee60****",
        "task_id": "640bc797bb684bd6960185651307****",
        "namespace": "SpeakerVerification",
        "name": "TaskResult",
        "status": 20000000,
        "status_message": "Gateway:SUCCESS:Success."
    },
     "payload": {
        "user_id": "123456",
        "appkey": "17d4c634****",      //获取Appkey请前往控制台:https://nls-portal.console.aliyun.com/applist
        "speaker_id": "test_speaker"
    }
}

header对象参数说明

参数名称

参数类型

参数说明

namespace

String

消息所属的命名空间,说话人识别为SpeakerVerification。

name

String

消息名称,TaskResult表示一个事件。

status

Integer

状态码,表示请求是否成功,具体请参见服务状态码

status_message

String

状态消息。

task_id

String

任务全局唯一ID,请记录该值,便于排查问题。

message_id

String

本次消息的ID。

服务状态码

在服务的每一次响应中,都包含status字段,即服务状态码。通用错误码、网关错误码、配置错误码各种取值含义如下。

  • 通用错误码

    错误码

    原因

    解决办法

    40000001

    身份认证失败

    检查使用的令牌是否正确,是否过期。

    40000002

    无效的消息

    检查发送的消息是否符合要求。

    40000010

    新用户免费试用3个月已到期

    继续使用需要付费商用,请前往控制台,在服务管理与开通页面,单击目标服务右侧的升级为商用版,进行付费使用。

    40000004

    空闲超时

    确认是否长时间(10秒)未发送数据到服务端。

    40000005

    请求数量过多

    检查是否超过了并发连接数或者每秒钟请求数。如果超过并发数,建议从免费版升级到商用版,或者商用版扩容并发资源。

    41010120

    客户端超时错误

    客户端连续10秒及以上未发送数据,导致客户端超时错误。

    40000000

    默认的客户端错误码

    检查对应的错误消息。

    50000000

    默认的服务端错误

    内部服务错误,需要客户端进行重试。

    50000001

    内部调用错误

    内部服务错误,需要客户端进行重试。

    52010001

    内部调用错误

    内部服务错误,需要客户端进行重试。

  • 网关错误码

    错误码

    原因

    解决办法

    40010001

    不支持的接口

    请升级到最新的SDK。

    40010002

    不支持的指令

    请升级到最新的SDK。

    40010003

    无效的指令

    请升级到最新的SDK。

    40010004

    客户端提前断开连接

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

    40010005

    任务状态错误

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

  • 配置错误码

    错误码

    原因

    解决办法

    40020105

    应用不存在

    解析路由时找不到应用。

    40020106

    Appkey和Token不匹配

    检查应用Appkey是否正确,是否与令牌归属同一个账号。

    40020503

    RAM用户(子账号)鉴权失败

    使用阿里云账号对调用的RAM用户(子账号)授权POP API的访问权限。