API reference

Updated at:

Speaker verification authenticates a speaker by comparing their spoken digit string with the registered voiceprint for that speaker in a one-to-one comparison. Authentication succeeds when the comparison meets the threshold.

Billing and concurrency limits

Speaker verification offers the Free Edition and Commercial Edition. For more information, see Service editions. For upgrade instructions, see Upgrade to the Commercial Edition.

For billing methods, see Billing; for concurrency limits, see Concurrency and QPS.

Usage limits

  • Audio must be PCM-encoded, 16-bit, mono, and sampled at 16000 Hz.

  • Audio for registration, update, and verification must not exceed 30 seconds.

  • A digit string is valid for 2 minutes.

  • A speaker ID (speaker_id) must not exceed 32 bytes.

  • Speaker verification authenticates speakers who read a specified digit string. It is not intended to identify different speakers in a multi-person conversation.

Endpoints

Access method

Description

URL

Public network

All servers can use this endpoint. It is the default endpoint in the SDK.

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

VPC internal network

For ECS instances in the China (Shanghai) region. Access the service from a VPC. Classic networks do not support internal access to the speech service.

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

Note

Internal network access does not incur public network data transfer fees for the ECS instance.

Interaction flow

The client sends JSON instructions and receives JSON events over WebSocket. Use one task ID for each operation and reuse it in subsequent instructions for that task. For Java SDK examples, see Speaker verification Java SDK.

Authentication

Use a token to authenticate when establishing the WebSocket connection. For instructions, see Obtain a token.

Obtain a digit string (ApplyDigit)

Send StartTask with action set to ApplyDigit and a speaker_id. After receiving TaskStarted, send StopTask and obtain the digit string from TaskResult.payload.digit. This operation does not send audio.

image

Register a voiceprint (Enroll)

Obtain a digit string, then send StartTask with action set to Enroll. After receiving TaskStarted, send audio of the speaker reading the digit string. When audio transmission is complete, send StopTask and wait for TaskResult to confirm the registration result.

A voiceprint cannot be registered again while a record for the specified speaker_id exists. Use Update to change an existing voiceprint. To register it again, first delete the existing record with Delete.

image

Update a voiceprint (Update)

Obtain a digit string, then send StartTask with action set to Update. After receiving TaskStarted, send audio of the speaker reading the digit string. When audio transmission is complete, send StopTask and wait for TaskResult to confirm the update result.

image

Verify a speaker (Verify)

Obtain a digit string, then send StartTask with action set to Verify. After receiving TaskStarted, send audio of the speaker reading the digit string. When audio transmission is complete, send StopTask and obtain the verification result from TaskResult.

image

Delete a voiceprint (Delete)

Send StartTask with action set to Delete and the speaker_id. After receiving TaskStarted, send StopTask and wait for TaskResult to confirm the deletion result. This operation does not send audio.

image

Requests

Obtain the Appkey for the project from the Intelligent Speech Interaction console and replace <Appkey> in the messages. The speaker_id, task ID, and digit string in the following messages are sample values. Use actual values for requests.

Request header parameters

Parameter

Type

Description

namespace

String

Set to SpeakerVerification.

name

String

Instruction: StartTask starts a task, and StopTask ends it.

appkey

String

The Appkey for the project.

task_id

String

A globally unique task ID generated by the client. Specify it in StartTask and reuse it in StopTask.

message_id

String

The ID of this message.

Start a task (StartTask)

Obtain a digit string (ApplyDigit)

Parameter

Type

Description

action

String

Set to ApplyDigit.

speaker_id

String

Required. Speaker ID, up to 32 bytes.

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

Register a voiceprint (Enroll)

Parameter

Type

Description

action

String

Set to Enroll.

format

String

Required. Audio encoding format. Set to pcm.

sample_rate

Integer

Required. Sample rate in Hz. Set to 16000.

speaker_id

String

Required. Speaker ID, up to 32 bytes.

digit

String

Required. The digit string obtained with 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 a voiceprint (Update)

Parameter

Type

Description

action

String

Set to Update.

format

String

Required. Audio encoding format. Set to pcm.

sample_rate

Integer

Required. Sample rate in Hz. Set to 16000.

speaker_id

String

Required. Speaker ID, up to 32 bytes.

digit

String

Required. The digit string obtained with 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 a speaker (Verify)

Parameter

Type

Description

action

String

Set to Verify.

format

String

Required. Audio encoding format. Set to pcm.

sample_rate

Integer

Required. Sample rate in Hz. Set to 16000.

speaker_id

String

Required. Speaker ID, up to 32 bytes.

digit

String

Required. The digit string obtained with 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 a voiceprint (Delete)

Parameter

Type

Description

action

String

Set to Delete.

speaker_id

String

Required. Speaker ID, up to 32 bytes.

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

End a task (StopTask)

Use StopTask to end all five types of tasks. For obtaining a digit string and deleting a voiceprint, send it after receiving TaskStarted. For registration, update, and verification, send it after audio transmission is complete. Wait for TaskResult after ending the task. Closing the connection does not replace the end instruction.

Parameter

Type

Description

task_id

String

The same task ID as in the client's StartTask request.

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

Responses

Response header parameters

Parameter

Type

Description

namespace

String

Always SpeakerVerification.

name

String

Event: TaskStarted confirms that a task has started, TaskResult contains the task result, and TaskFailed indicates a task failure.

status

Integer

Service status code. 20000000 indicates success. For error codes, see Service status codes.

status_text

String

Status message.

task_id

String

The task ID from the client request. Use it to identify the task.

message_id

String

The ID of this message.

Task started event (TaskStarted)

TaskStarted confirms that a task has started. It does not contain the final result.

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

Task result event (TaskResult)

Obtain a digit string (ApplyDigit)

Parameter

Type

Description

user_id

String

Alibaba Cloud account ID.

appkey

String

The Appkey for the project.

speaker_id

String

Speaker ID.

digit

String

An eight-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"
    }
}

Register a voiceprint (Enroll)

Parameter

Type

Description

user_id

String

Alibaba Cloud account ID.

appkey

String

The Appkey for the project.

speaker_id

String

Speaker ID.

digit

String

The digit string used for this operation.

{
    "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 a voiceprint (Update)

Parameter

Type

Description

user_id

String

Alibaba Cloud account ID.

appkey

String

The Appkey for the project.

speaker_id

String

Speaker ID.

digit

String

The digit string used for this operation.

{
    "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 a speaker (Verify)

Parameter

Type

Description

user_id

String

Alibaba Cloud account ID.

appkey

String

The Appkey for the project.

speaker_id

String

Speaker ID.

digit

String

The digit string used for this operation.

score

String

Confidence score in the range [0.0, 100.0]. A larger value indicates higher confidence.

decision

Integer

Verification result: 1 indicates success, and 0 indicates failure.

{
    "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 a voiceprint (Delete)

Parameter

Type

Description

user_id

String

Alibaba Cloud account ID.

appkey

String

The Appkey for the project.

speaker_id

String

Speaker 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"
    }
}

Service status codes

The header.status field in a service response contains the service status code. If an error occurs, check status_text for details and take the appropriate action.

General error codes

Error code

Cause

Solution

40000001

Authentication failed

Check whether the token is correct or has expired.

40000002

Invalid message

Check whether the message conforms to the protocol.

40000010

The three-month free trial has ended

Upgrade to the Commercial Edition to continue using the service. For instructions, see Upgrade to the Commercial Edition.

40000004

Idle timeout

Check whether no data has been sent to the server for 10 consecutive seconds.

40000005

Too many requests

Check whether the concurrency or QPS limit has been exceeded. If the concurrency limit is exceeded, upgrade to the Commercial Edition or increase its concurrency quota.

41010120

Client timeout

The client has not sent data for at least 10 consecutive seconds. Check audio transmission.

40000000

Client error

Check the request based on the error message. Gateway:CLIENT_ERROR:vpr profile is exist! indicates that a voiceprint record for the specified speaker_id already exists. Use Update to change it, delete it with Delete before registering it again, or use a new speaker_id to register another record.

50000000

Server error

An internal service error occurred. Retry the request.

50000001

Internal call error

An internal service error occurred. Retry the request.

52010001

Internal call error

An internal service error occurred. Retry the request.

Gateway error codes

Error code

Cause

Solution

40010001

Unsupported interface

Upgrade to the latest SDK.

40010002

Unsupported instruction

Upgrade to the latest SDK.

40010003

Invalid instruction

Upgrade to the latest SDK.

40010004

Client disconnected prematurely

Check whether the connection was closed before the request completed.

40010005

Invalid task state

Check whether an instruction was sent that cannot be processed in the current task state.

Configuration error codes

Error code

Cause

Solution

40020105

Application does not exist

The application cannot be found when resolving the route. Check the Appkey.

40020106

Appkey and token do not match

Check whether the Appkey is correct and belongs to the same account as the token.

40020503

RAM user authentication failed

Use the Alibaba Cloud account to grant the RAM user permissions to access POP APIs.