API reference
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. |
|
|
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. |
|
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.
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.
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.
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.
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.
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 |
|
name |
String |
Instruction: |
|
appkey |
String |
The Appkey for the project. |
|
task_id |
String |
A globally unique task ID generated by the client. Specify it in |
|
message_id |
String |
The ID of this message. |
Start a task (StartTask)
Obtain a digit string (ApplyDigit)
|
Parameter |
Type |
Description |
|
action |
String |
Set to |
|
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 |
|
format |
String |
Required. Audio encoding format. Set to |
|
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 |
{
"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 |
|
format |
String |
Required. Audio encoding format. Set to |
|
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 |
{
"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 |
|
format |
String |
Required. Audio encoding format. Set to |
|
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 |
{
"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 |
|
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 |
{
"header": {
"message_id": "fedcba9876543210fedcba9876543211",
"task_id": "0123456789abcdef0123456789abcdef",
"namespace": "SpeakerVerification",
"name": "StopTask",
"appkey": "<Appkey>"
},
"payload": {}
}
Responses
Response header parameters
|
Parameter |
Type |
Description |
|
namespace |
String |
Always |
|
name |
String |
Event: |
|
status |
Integer |
Service status code. |
|
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. |
|
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. |