Voiceprint Recognition Service API

Feature Introduction

Voiceprint recognition provides functions for voiceprint registration, verification, and deregistration.

Call Limitations

• Voiceprint samples must be in PCM or WAV format, and the audio should be mono.
• The bit depth of the voiceprint samples must be 16-bit, and the sampling rate must be 16000 Hz.
• The duration of the voiceprint samples must be between 3 to 20 seconds, with a recommended duration of 5 to 10 seconds.

URL

http://<ip_address>:7800

Interaction Process

User Information Query API

Queries the voiceprint registration status of a specified user. This can be used to check user information or to verify the availability of a username before registration.

Request Line

POST /checkUser HTTP/1.1

Request Headers

Request Parameters

The client sends a request where parameters need to be set in the body. The meaning of each parameter is as follows:

Sample request body:

{
    "user_name": "test"
}

Response Results

The Content-Type field of the HTTPS headers in the response is application/json, and the response results are contained in the HTTP Body. The fields in the response are as follows:

Successful Response

The status field in the body is 00000.

Example of a successful response:

{
    "task_id":"4848d4f8-b511-4c69-a1c1-61a54bbb3bb8",
    "status": "00000",
    "message": "success",
    "data": {
        "user_name": "test",
        "enroll_num": 0,
        "update_time": "",
        "group_id": null
    }
}

Error Response

Any status field in the body that is not 00000 is considered an error response, and this field can be used as an indicator of whether the response was successful.

Example of an error response:

{
    "task_id":"4848d4f8-b511-4c69-a1c1-61a54bbb3bb8",
    "status": "22151",
    "message": "service error",
    "data": {
        "user_name":"test"
    }
}

User List Query API

Returns all registered voiceprint information (including completed and incomplete registrations), including usernames, the number of successful registrations, and the time of the last registration. A voiceprint registration is considered complete after 3 successful registrations.

Request Line

GET /getUsers HTTP/1.1

Request Parameters

None

Response Results

The Content-Type field of the HTTP Headers in the response is application/json, and the response results are contained in the HTTP Body.

The fields in the response are as follows:

Successful Response

The status field in the body is 00000.

Example of a successful response:

{
    "task_id":"4848d4f8-b511-4c69-a1c1-61a54bbb3bb8",
    "status": "00000",
    "message": "success",
    "data": [
        {
            "user_name": "test1",
            "enroll_num": 3,
            "update_time": "2022-01-01 12:00:00",
            "group_id": 0
        },
        {
            "user_name": "test2",
            "enroll_num": 2,
            "update_time": "2022-01-01 13:01:00",
            "group_id": 0
        }
    ]
}

Error Response

Any status field in the body that is not 00000 is considered an error response, and this field can be used as an indicator of whether the response was successful.

Example of an error response:

{
    "task_id":"4848d4f8-b511-4c69-a1c1-61a54bbb3bb8",
    "status": "22151",
    "message": "service error",
    "data": null
}

Voiceprint Registration API

The client sends an HTTP POST request with registration information to the server, and the server returns an HTTP response with the result of this registration. A voiceprint registration is considered complete only after 3 successful registrations, meaning the voiceprint registration interface must be called 3 times.

Request Line

POST /enroll HTTP/1.1

Request Headers

Request Parameters

The client sends a request where parameters need to be set in the body. The meaning of each parameter is as follows:

Note: The user_name must be globally unique (even if group_id is different). Username specifications: 4 to 16 characters, and can include numbers, letters, underscores, and hyphens. The group_id defines the comparison scope during verification. If not specified, the default ID is 0. If the group_id values differ during the 3 registration requests, the value from the 3rd request will be used.

Example of a request body:

{
    "format": "wav",
    "sample_rate": 16000,
    "user_name": "test",
    "enroll_num": 1,
    "data": "base64 encoded audio data"
}

Response Results

The Content-Type field of the HTTPS headers in the response is application/json, and the response results are contained in the HTTP Body.

The fields in the response are as follows:

Successful Response

The status field in the body is 00000.

Example of a successful response:

• First registration successful

{
    "task_id":"4848d4f8-b511-4c69-a1c1-61a54bbb3bb8",
    "status": "00000",
    "message": "the first time you enroll successfully, you need to enroll twice more",
    "data": {
        "user_name": "test",
        "enroll_num": 1
    }
}

• Second registration successful

{
    "task_id":"4848d4f8-b511-4c69-a1c1-61a54bbb3bb8",
    "status": "00000",
    "message": "the second registration is successful, please register one more time",
    "data": {
        "user_name":"test",
        "enroll_num": 2
    }
}

• Third registration successful

{
    "task_id":"4848d4f8-b511-4c69-a1c1-61a54bbb3bb8",
    "status": "00000",
    "message": "the third registration is successful, registration completed",
    "data": {
        "user_name":"test",
        "enroll_num": 3
    }
}

Error Response

Any status field in the body that is not 00000 is considered an error response, and this field can be used as an indicator of whether the response was successful.

Example of an error response:

{
    "task_id":"4848d4f8-b511-4c69-a1c1-61a54bbb3bb8",
    "status": "22131",
    "message": "invalid operation: the registration process has already been completed",
    "data": {
        "user_name":"test",
        "enroll_num": 3
    }
}

Voiceprint Verification API

The client sends an HTTP POST request with verification information to the server, and the server returns an HTTP response with the result of the verification. Verification can be in "1-v-1" or "1-v-N" mode. For related concepts, please refer to the "Basic Terms" section of the Voiceprint Recognition Service User Manual.

Request Line

POST /verify HTTP/1.1

Request Headers

Request Parameters

The client sends a request where parameters need to be set in the body. The meaning of each parameter is as follows:

Example of a request body:

1-v-1 Verification

{
    "format": "wav",
    "sample_rate": 16000,
    "user_name": "test",
    "data": "base64 encoded audio data"
}

1-v-N Verification (Global Matching)

{
    "format": "wav",
    "sample_rate": 16000,
    "data": "base64 encoded audio data"
}

1-v-N Verification (Specified Matching Groups)

{
    "format": "wav",
    "sample_rate": 16000,
    "group_id": [0, 1, 2],
    "data": "base64 encoded audio data"
}

Response Results

The Content-Type field of the HTTPS headers in the response is application/json, and the response results are contained in the HTTP Body.

The fields in the response are as follows:

Successful Response

The status field in the body is 00000.

The confidence field indicates the confidence level (matching similarity) of the verification.

Example of a successful response:

1-v-1 Verification

{
    "task_id":"4848d4f8-b511-4c69-a1c1-61a54bbb3bb8",
    "status": "00000",
    "message": "success",
    “data”:{
        "user_name":"test",
        "confidence":0.76
    }
}

1-v-1 Verification

{
    "task_id":"4848d4f8-b511-4c69-a1c1-61a54bbb3bb8",
    "status":"00000",
    "message":"success",
    "data":[
        {
            "user_name":"test3",
            "confidence":0.98,
            "group_id":0
        },
        {
            "user_name":"test1",
            "confidence":0.76,
            "group_id":0            
        },
        {
            "user_name":"test2",
            "confidence":0.71,
            "group_id":1
        }
    ]
}

Error Response

Any status field in the body that is not 00000 is considered an error response, and this field can be used as an indicator of whether the response was successful.

Example of a error response:

{
    "task_id":"4848d4f8-b511-4c69-a1c1-61a54bbb3bb8",
    "status": "22102",
    "message": "the user_name hasn't been registered completely",
    "data": {
        "user_name":"test",
        "enroll_num": 2
    }
}

Voiceprint Deregistration API

The client sends an HTTP POST request with deregistration information to the server, and the server returns an HTTP response with the result of the deregistration.

Request Line

POST /unregister HTTP/1.1

Request Headers

Request Parameters

The client sends a request where parameters need to be set in the body. The meaning of each parameter is as follows:

Sample request body:

{
    "user_name": "test"
}

Response Results

The Content-Type field of the HTTPS headers in the response is application/json, and the response results are contained in the HTTP Body.

The fields in the response are as follows:

Successful Response

The status field in the body is 00000.

Example of a successful response:

{
    "task_id":"4848d4f8-b511-4c69-a1c1-61a54bbb3bb8",
    "status": "00000",
    "message": "success",
    "data": {
        "user_name": "test"
    }
}

Error Response

Any status field in the body that is not 00000 is considered an error response, and this field can be used as an indicator of whether the response was successful.

Example of an error response:

{
    "task_id":"4848d4f8-b511-4c69-a1c1-61a54bbb3bb8",
    "status": "22135",
    "message": "unregistration failed: this user_name hasn't been registered",
    "data": {
        "user_name": "test"
    }
}

Service Status Codes

Every response from the service will include the status and message fields, which indicate the status code and description of the status code. The service status codes are as follows:

Best Practices

1. Before registering a voiceprint, call the “User Information Query Interface” to check the availability of the username. Once you confirm the username is not registered, proceed with the “Voiceprint Registration Interface.”
2. Longer audio lengths for registration and verification generally improve recognition accuracy but slow down recognition speed. It is recommended to balance accuracy and speed, with a suggested audio length of 5 to 10 seconds.
3. During voiceprint verification, the voiceprint confidence (matching similarity) is returned. You might set the threshold to 0.7 (i.e., confidence above 0.7 is considered the same person).

FAQ

"Voiceprint mismatch with that of the initial registration" during registration

The second or third registration differs significantly from the initial registration, preventing completion. You can deregister the voiceprint and attempt registration again.