REST API Reference

General

Version of VoiceLiveness Rest Services

GET /version

Version of VoiceLiveness Rest Services

Returns the version of voice liveness services.

Status Codes

200 OK – OK
500 Internal Server Error – Internal error.

200 Response schema:

string

Example response:

HTTP/1.1 200 OK
Content-Type: text/plain

Aware VoiceLiveness Library, version x.x.x

500 Response schema:

Name	Type	Description
error	object
code	integer	Error code
description	string	Error description

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain

{
    "error": {
        "code": "",
        "description": ""
    }
}

Analyze liveness given voice samples

POST /analyze

Analyze liveness given voice samples

Request schema:

Name	Type	Description
voice	object	Voice object.
voiceSamples	(array of voiceSamples)	List of Base64 encoded voiceSample data.
metadata	metadata
workflow	string	(Optional) Workflow to use for liveness detection. Values: alfa2, alfa4, alfa6
securityLevel	number	Security level threshold to override the default workflow.

Example request:

POST /analyze HTTP/1.1
Host: example.com
Content-Type: text/plain

{
    "voice": {
        "voiceSamples": [
            {
                "data": "base64 voice sample"
            }
        ],
        "workflow": "alfa4",
        "meta_data": {
            "client_device_brand": "Apple",
            "client_device_model": "iPhone 8",
            "client_os_version": "11.0.3",
            "client_version": "KnomiSLive_v:2.4.1_b:0.0.0_sdk_v:2.4.1_b:0.0.0",
            "localization": "en-US",
            "programming_language_version": "Swift 4.1",
            "username": "test"
        }
    }
}

Status Codes

200 OK – Success
400 Bad Request – The request is not valid
500 Internal Server Error – Internal error.

200 Response schema:

Name	Type	Description
voice	object	Voice object
livenessResult	livenessResult

Example response:

HTTP/1.1 200 OK
Content-Type: text/plain

{
    "voice": {
        "livenessResult": {
            "decision": "LIVE",
            "score": 100.0,
            "score_frr": 5.0
        }
    }
}

400 Response schema:

Name	Type	Description
error	object
code	integer	Error code Values: -1 (Unknown Error), -2 (Invalid Input JSON), -3 (Missing Mandatory Field), -4 (Field Has Wrong Type), -5 (Invalid Base64 String), -6 (Invalid Value), -7 (Invalid Voice Sample), -8 (Missing Voice Samples), -9 (Invalid Workflow)
description	string	Error description

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "error": {
        "code": -2,
        "description": "Request was not valid JSON."
    }
}

500 Response schema:

Name	Type	Description
error	object
code	integer	Error code
description	string	Error description

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain

{
    "error": {
        "code": "",
        "description": ""
    }
}

Encrypted version of analyze endpoint.

POST /analyzeEncrypted

Encrypted version of analyze endpoint.

Please Note:

Encrypted request data is generated by Knomi software.

Request schema:

Name	Type	Description
key	string	Encrypted request ‘key’ value
iv	string	Encrypted request ‘iv’ value
p	string	Encrypted request ‘p’ value

Example request:

POST /analyzeEncrypted HTTP/1.1
Host: example.com
Content-Type: text/plain

{
    "key": "string",
    "iv": "string",
    "p": "string"
}

Status Codes

200 OK – Success
400 Bad Request – The request is not valid
500 Internal Server Error – Internal error.

200 Response schema:

Name	Type	Description
voice	object	Voice object
livenessResult	livenessResult

Example response:

HTTP/1.1 200 OK
Content-Type: text/plain

{
    "voice": {
        "livenessResult": {
            "decision": "LIVE",
            "score": 100.0,
            "score_frr": 5.0
        }
    }
}

400 Response schema:

Name	Type	Description
error	object
code	integer	Error code Values: -1 (Unknown Error), -2 (Invalid Input JSON), -3 (Missing Mandatory Field), -4 (Field Has Wrong Type), -5 (Invalid Base64 String), -6 (Invalid Value), -7 (Invalid Voice Sample), -8 (Missing Voice Samples), -9 (Invalid Workflow)
description	string	Error description

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "error": {
        "code": -2,
        "description": "Request was not valid JSON."
    }
}

500 Response schema:

Name	Type	Description
error	object
code	integer	Error code
description	string	Error description

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain

{
    "error": {
        "code": "",
        "description": ""
    }
}

Calculate the length of the given voice sample (in seconds)

POST /calculateVoiceLength

Calculate the length of the given voice sample (in seconds)

Request schema:

Name	Type	Description
voice	object	Voice object.
voiceSamples	(array of voiceSamples)	List of Base64 encoded voiceSample data.
metadata	metadata

Example request:

POST /calculateVoiceLength HTTP/1.1
Host: example.com
Content-Type: text/plain

{
    "voice": {
        "voiceSamples": [
            {
                "data": "base64 voice sample"
            }
        ],
        "meta_data": {
            "client_device_brand": "Apple",
            "client_device_model": "iPhone 8",
            "client_os_version": "11.0.3",
            "client_version": "KnomiSLive_v:2.4.1_b:0.0.0_sdk_v:2.4.1_b:0.0.0",
            "localization": "en-US",
            "programming_language_version": "Swift 4.1",
            "username": "test"
        }
    }
}

Status Codes

200 OK – Success
400 Bad Request – The request is not valid
500 Internal Server Error – Internal error.

200 Response schema:

Name	Type	Description
voice	object	Voice object
voiceSamples	(array of objects)	List of Base64 encoded voiceSample data.
voiceLengthSeconds	number	Length of the voice sample.

Example response:

HTTP/1.1 200 OK
Content-Type: text/plain

{
    "voice": {
        "voiceSamples": [
            {
                "voiceLengthSeconds": 2.23
            }
        ]
    }
}

400 Response schema:

Name	Type	Description
error	object
code	integer	Error code Values: -1 (Unknown Error), -2 (Invalid Input JSON), -3 (Missing Mandatory Field), -4 (Field Has Wrong Type), -5 (Invalid Base64 String), -6 (Invalid Value), -7 (Invalid Voice Sample), -8 (Missing Voice Samples), -9 (Invalid Workflow)
description	string	Error description

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "error": {
        "code": -2,
        "description": "Request was not valid JSON."
    }
}

500 Response schema:

Name	Type	Description
error	object
code	integer	Error code
description	string	Error description

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain

{
    "error": {
        "code": "",
        "description": ""
    }
}

Encrypted version of calculateVoiceLength endpoint.

POST /calculateVoiceLengthEncrypted

Encrypted version of calculateVoiceLength endpoint.

Please Note:

Encrypted request data is generated by Knomi software.

Request schema:

Name	Type	Description
key	string	Encrypted request ‘key’ value
iv	string	Encrypted request ‘iv’ value
p	string	Encrypted request ‘p’ value

Example request:

POST /calculateVoiceLengthEncrypted HTTP/1.1
Host: example.com
Content-Type: text/plain

{
    "key": "string",
    "iv": "string",
    "p": "string"
}

Status Codes

200 OK – Success
400 Bad Request – The request is not valid
500 Internal Server Error – Internal error.

200 Response schema:

Name	Type	Description
voice	object	Voice object
voiceSamples	(array of objects)	List of Base64 encoded voiceSample data.
voiceLengthSeconds	number	Length of the voice sample.

Example response:

HTTP/1.1 200 OK
Content-Type: text/plain

{
    "voice": {
        "voiceSamples": [
            {
                "voiceLengthSeconds": 2.23
            }
        ]
    }
}

400 Response schema:

Name	Type	Description
error	object
code	integer	Error code Values: -1 (Unknown Error), -2 (Invalid Input JSON), -3 (Missing Mandatory Field), -4 (Field Has Wrong Type), -5 (Invalid Base64 String), -6 (Invalid Value), -7 (Invalid Voice Sample), -8 (Missing Voice Samples), -9 (Invalid Workflow)
description	string	Error description

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "error": {
        "code": -2,
        "description": "Request was not valid JSON."
    }
}

500 Response schema:

Name	Type	Description
error	object
code	integer	Error code
description	string	Error description

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain

{
    "error": {
        "code": "",
        "description": ""
    }
}

Structure Reference

analyzeRequest Model Structure

Name

Type

Description

voice

object

Voice object.

   voiceSamples

(array of voiceSamples)

List of Base64 encoded voiceSample data.

   metadata

metadata

   workflow

string

(Optional) Workflow to use for liveness detection. Values: alfa2, alfa4, alfa6

   securityLevel

number

Security level threshold to override the default workflow.

analyzeResponse Model Structure

Name

Type

Description

voice

object

Voice object

livenessResult

livenessResult

voiceLivenessRequestEncrypted Model Structure

Name

Type

Description

key

string

Encrypted request ‘key’ value

iv

string

Encrypted request ‘iv’ value

p

string

Encrypted request ‘p’ value

calculateVoiceLengthRequest Model Structure

Name

Type

Description

voice

object

Voice object.

voiceSamples

(array of voiceSamples)

List of Base64 encoded voiceSample data.

metadata

metadata

calculateVoiceLengthResponse Model Structure

Name

Type

Description

voice

object

Voice object

voiceSamples

(array of objects)

List of Base64 encoded voiceSample data.

voiceLengthSeconds

number

Length of the voice sample.

livenessResult Model Structure

Liveness result object

Name

Type

Description

score

number

Liveness score of the voice samples. Values: -1.0 (Error), 0.0 (Not Live), 100.0 (Live)

decision

string

classify liveness score to result type Values: LIVE (score 100), SPOOF (score 0), UNABLE_TO_CALCULATE_LIVENESS (error score -1)

score_frr

number

Score used to threshold by false rejection rate. See the manual for more info.

voiceSampleObject Model Structure

Name

Type

Description

data

string

Base64 encoded voice sample.

metadata Model Structure

(Optional) metadata associated with the transaction

Name

Type

Description

username

string

(Optional) Username associated with the transaction

client_device_brand

string

(Optional) Client’s device brand

client_device_model

string

(Optional) Client’s device model

client_os_version

string

(Optional) Client’s os version

client_version

string

(Optional) Client’s application version

localization

string

(Optional) Client’s localization

programming_language_version

string

(Optional) Client’s programming language version

400Error Model Structure

Name

Type

Description

code

integer

Error code Values: -1 (Unknown Error), -2 (Invalid Input JSON), -3 (Missing Mandatory Field), -4 (Field Has Wrong Type), -5 (Invalid Base64 String), -6 (Invalid Value), -7 (Invalid Voice Sample), -8 (Missing Voice Samples), -9 (Invalid Workflow)

description

string

Error description

500Error Model Structure

Name

Type

Description

code

integer

Error code

description

string

Error description