Definition¶
This service is a REST API where the following endpoints are exposed: Public Base URL (v1):
https://<base\_url>/daspeak/v1/
Postman Collection: Download Resources: None
| Method | Public URL | Description |
|---|---|---|
| GET | /alive | Checks if the service is up. |
| GET | /models | Get a list hashes of all available models in das-Peak service. |
| POST | /models/metadata | Provides metadata information about a specific hash model. |
| POST | /models/calibration | Get info about calibration modes that a specific model supports. |
| POST | /models/metadata/from-credential | Provides metadata information about a specific voice credential, among others, model hash used to create it. |
| POST | /credential/wav | Generate a biometric credential from a given audio input, using the latest available model. |
| POST | /similarity/credential2wav | Computes the voice similarity between an audio input and a previously generated voice biometric credential, and returns how similar are both voices. |
| POST | /similarity/wav2wav | Computes the voice similarity between two audio inputs, and returns how similar are both voices. |
| POST | /identification/wav2credentials | Computes the voice similarity between an input wav and a list of voice credentials, and returns the highest score ID and a list of all results. A result contains credential ID and its score. |
| POST | models/{hash}/credential/wav | Generate a biometric credential from a given audio input, using the hash model. It is possible to obtain hash with endpoint /models. |
Check if the service is alive¶
The service receives a GET request with no params, and returns a 200 status code indicating that the server is up.
GET /alive
https://api-work.eu.veri-das.com/daspeak/v1/alive
Response: 200
Empty response.
Response: 500
Server error response.
Content-Type: application/json
| exception | error message |
|---|---|
| ServerError | Unexpected server fatal error |
Get list of available models¶
The service receives a GET request with no params, and returns the available embedding model hashes.
GET /models
https://api-work.eu.veri-das.com/daspeak/v1/models
Response: 200
Returns list of models sorted by their numeric tag (descending order).
Example:
{
"version": "1.0",
"models": [
"1b40a9b479b131e7acb9cab797f929e28eb5dffac86ce1d71d83c564",
"38da15f1b61fb5800c5928f6f1437aed7a0b0e7921fa6bb7852c5783",
"2b045e0bc0ba5426651d3e4638403da43e5f843afaa32c3fc5773626"
]
}
Response: 500
Server error response.
Content-Type: application/json
| exception | error message |
|---|---|
| ServerError | Unexpected server fatal error |
Obtain metadata from a model¶
This endpoint is used to obtain the metadata info of a model.
POST /models/metadata
Request Body
Request for model metadata information.
| Name | Req. | Type | Description |
|---|---|---|---|
| hash | yes | string | A hash given as hex digest, same as returned by |
https://api-work.eu.veri-das.com/daspeak/v1/models/metadata
Response: 200
Returns metadata info of a model given its hash.
Content-Type: application/json
| Name | Req. | Type | Description |
|---|---|---|---|
| version | Yes | string | API version |
| metadata | yes | Dictionary | returns "hash":model hash input and "description": model information. |
Example:
{
"version": "1.0",
"metadata": {
"hash": "1b40a9b479b131e7acb9cab797f929e28eb5dffac86ce1d71d83c564",
"description": "Speaker Recognition model created on 10/02/2020 that works with 8 kHz audio"
}
}
Response: 400 Error: bad request.
Content-Type: application/json
| exception | error message |
|---|---|
| error | The model is not available. |
| exception | ModelNotAvailable |
Obtain calibration modes of a model¶
This endpoint is used to obtain the info about calibration modes that a specific model supports.
POST /models/calibration
Request Body
Request for model metadata information.
| Name | Req. | Type | Description |
|---|---|---|---|
| hash | yes | string | A hash given as hex digest, same as returned by |
Example: https://api-work.eu.veri-das.com/daspeak/v1/models/calibration
Response: 200
Returns calibration modes of a model given its hash.
Content-Type: application/json
| Name | Req. | Type | Description |
|---|---|---|---|
| version | yes | string | API version |
| calibrations | yes | Dictionary | Results calibration models that this model supports. Different calibration types are: ["lossless-audio","telephone-channel","no-calibration "] |
Example:
{
"version": "1.0",
"calibrations": [
"lossless-audio",
"telephone-channel",
"no-calibration"
]
}
Response: 400 Error: bad request.
Content-Type: application/json
| exception | error message |
|---|---|
| error | The model is not available. |
| exception | ModelNotAvailable |
Obtain metadata from a voice biometric credential¶
This endpoint is used to obtain the info about metadata from a given voice credential.
POST /metadata/from-credential
Request Body
Request for voice credential metadata information.
| Name | Req. | Type | Description |
|---|---|---|---|
| credential | yes | string | voice credential returned by |
Example: https://api-work.eu.veri-das.com/daspeak/v1/metadata/from-credential
Response: 200
Returns metadata information of a given voice credential.
Content-Type: application/json
| Name | Req. | Type | Description |
|---|---|---|---|
| version | yes | string | API version |
| metadata | yes | Dictionary | returns "hash": model has been used to create the credential and "description": model information. |
Example:
{
"version": "1.0",
"metadata": {
"hash": "1b40a9b479b131e7acb9cab797f929e28eb5dffac86ce1d71d83c564",
"description": "Speaker Recognition model created on 10/02/2020 that works with 8 kHz audio"
}
}
Response: 400
Error: bad request.
Content-Type: application/json
| exception | error message |
|---|---|
| error | Incorrect Padding. |
| exception | ValueError |
Generate a voice biometric credential¶
This endpoint is used to generate a voice biometric credential from a given audio input, using the latest available model. The biometric credential size is 1.1 Kbytes.
POST /credential/wav
Request Body
Request for voice biometric credential generation.
| Name | Req. | Type | Description |
|---|---|---|---|
| audio | yes | WAV file | Audio with the target speaker voice. |
| channel | no | int | The channel on which the biometrics operation shall be applied, in case the audio has more than one. (DEFAULT channel = 1) |
Request header
Request for voice authenticity checking.
| Name | Req. | Type | Description |
|---|---|---|---|
| X-Check-Authenticity | No | Header | This header activates the voice authenticity check. If it is present in the query, in the response there will be a authenticity value in range [0,1] indicating if the voice is authentic (close 1), or a spoof attack (close to 0). |
| X-Veridas-RTag | No | Header | This header allows to tagger this query with a personal string. This tag needs to be a ASCII string with a maximum size of 64 characters. |
Example: https://api-work.eu.veri-das.com/daspeak/v1/credential/wav
Response: 200
Returns one voice biometric credential for the given audio file.
Content-Type: application/json
| Name | Req. | Type | Description |
|---|---|---|---|
| credential | yes | string | A biometric credential string |
| version | yes | string | API version |
| model | yes | Dictionary | Dictionary with hash and mode fields, information about the model used to generate the voice credential. |
| authenticity | No | number | voice authenticity in range [0,1]. when this number is close to 1 indicates it is authentic and, if it is close to 0, it means spoof. |
Example:
{
"credential": "APUhOWxROgu",
"model": {
"hash": "e7acb9cab797f929e0",
"mode": "speaker-recognition-8k"
},
"version": "1.0",
"authenticity": 0.98036
}
Response: 400
Request format error.
Content-Type: application/json
| exception | error message |
|---|---|
| InputException | The wav has more channels than are accepted by the system |
| InputException | The sample rate is not supported, must be 8 Khz or 16 Khz |
| InputException | The bits per sample is not supported, must be 16 bits/sample |
| InputException | The wav duration is longer than 30 seconds |
| SignalNoiseRatioException | Noise level exceeded |
| VoiceDurationIsNotEnoughException | Voice duration is less than 3 seconds |
| InvalidChannelException | Invalid specified channel/s |
Response: 500
Server error response.
Content-Type: application/json
| exception | error message |
|---|---|
| Exception | Error opening <_io.BytesIO object at 0x7f6baab4dbf8>: File contains data in an unknown format. |
Compute similarity between voice biometric credential and audio input¶
Computes the voice similarity between an audio input and a previously generated voice biometric credential, and returns how similar are both voices.
POST /similarity/credential2wav
Request Body
Request for voice verification with a voice biometric credentials and wav audio input.
| Name | Req. | Type | Description |
|---|---|---|---|
| credential_reference | yes | string | A reference voice biometric credential string generated with das-Peak service. |
| audio_to_evaluate | yes | WAV file | Audio to evaluate with the speaker voice. |
| calibration | no | string | Calibration type to compare credential and audio input. The calibration modes are: ["lossless-audio","telephone-channel","no-calibration"]. By default "telephone-channel". If SDKs are used for audio capturing, it is necessary to use "lossless-audio". |
| channel | no | int | The channel on which the biometrics operation shall be applied, in case the audio has more than one. (DEFAULT channel = 1) |
Request header
Request for voice authenticity checking.
| Name | Req. | Type | Description |
|---|---|---|---|
| X-Check-Authenticity | No | Header | This header activates the voice authenticity check. If it is present in the query, in the response there will be an authenticity value in range [0,1] indicating if the voice is authentic (close 1), or a spoof attack (close to 0). |
| X-Veridas-RTag | No | Header | This header allows to tagger this query with a personal string. This tag needs to be a ASCII string with a maximum size of 64 characters. |
Example: https://api-work.eu.veri-das.com/daspeak/v1/similarity/credential2wav
Response: 200
Returns the confidence (or similarity) between the audio to evaluate and the biometric voice credential, being more similar as much close this number is to one. The number is in range [0,1].
Content-Type: application/json
| Name | Req . | Type | Description |
|---|---|---|---|
| score | yes | number | A probability number in range [0,1] |
| version | yes | string | API version |
| model | yes | Dictionary | Dictionary with hash and mode fields |
| authenticity_to_evaluate | No | number | audio voice authenticity in range [0,1]. when this number is close to 1 indicates it is authentic and, if it is close to 0, it means spoof. |
Example:
{
"score": 0.91,
"model": {
"hash": "1b40a9b479b131ef929",
"mode": "speaker-recognition-8k"
},
"version": "1.0",
"authenticity_to_evaluate": 0.98036
}
Response: 400
Request format error.
Content-Type: application/json
| exception | error message |
|---|---|
| InputException | The wav has more channels than are accepted by the system |
| InputException | The sample rate is not supported, must be 8 Khz or 16 Khz |
| InputException | The bits per sample is not supported, must be 16 bits/sample |
| InputException | The wav duration is longer than 30 seconds |
| SignalNoiseRatioException | Noise level exceeded |
| VoiceDurationIsNotEnoughException | Voice duration is less than 3 seconds |
| InvalidChannelException | Invalid specified channel/s |
Response: 500
Server error response.
Content-Type: application/json
| exception | error message |
|---|---|
| Exception | Decryption error |
| Exception | Incorrect padding |
| Exception | Error opening <_io.BytesIO object at 0x7f6baab4dbf8>: File contains data in an unknown format. |
Compute similarity between two audio inputs¶
Computes the voice similarity between two audio inputs, and returns how similar are both
voices.
POST /similarity/wav2wav
Request Body
Request for voice verification with two audios.
| Name | Req. | Type | Description |
|---|---|---|---|
| audio_reference | yes | WAV file | Audio with the reference speaker voice. |
| audio_to_evaluate | yes | WAV file | Audio to evaluate with speaker voice. |
| calibration | no | string | Calibration type to compare credential and audio input. The calibration modes are: ["lossless-audio","telephone-channel","no-calibration"]. By default "telephone-channel". If SDKs are used for audio capturing, it is necessary to use "lossless-audio". |
| channel_reference | no | int | The channel on which the biometrics operation shall be applied, in case the audio_reference has more than one. (DEFAULT channel = 1) |
| channel_to_evaluate | no | int | The channel on which the biometrics operation shall be applied, in case the audio_to_evaluate has more than one. (DEFAULT channel = 1) |
Request header
Request for voice authenticity checking.
| Name | Req. | Type | Description |
|---|---|---|---|
| X-Check-Authenticity | No | Header | This header activates the voice authenticity check. If it is present in the query, in the response there will be an authenticity value in range [0,1] indicating if the voice is authentic (close 1), or a spoof attack (close to 0). |
| X-Veridas-RTag | No | Header | This header allows to tagger this query with a personal string. This tag needs to be a ASCII string with a maximum size of 64 characters. |
Example: https://api-work.eu.veri-das.com/daspeak/v1/similarity/wav2wav
Response: 200
Returns the confidence (or similarity) between both speaker voices, being more similar as much close this number is to one. The number is in range [0,1].
Content-Type: application/json
| Name | Req. | Type | Description |
|---|---|---|---|
| score | yes | number | A probability number in range [0,1] |
| version | yes | string | API version |
| model | yes | Dictionary | Dictionary with hash and mode fields |
| authenticity_reference | No | number | voice authenticity of the audio reference in range [0,1]. when this number is close to 1 indicates it is authentic and, if it is close to 0, it means spoof. |
| authenticity_to_evaluate | No | number | voice authenticity of the audio to evaluate in range [0,1]. when this number is close to 1 indicates it is authentic and, if it is close to 0, it means spoof. |
Example:
{
"score": 0.81,
"model": {
"hash": "1b40a9b479b131e7acb",
"mode": "speaker-recognition-8k" },
"version": "1.0",
"authenticity_reference": 0.98036,
"authenticity_to_evaluate": 0.9915
}
Response: 400 Request format error.
Content-Type: application/json
| exception | error message |
|---|---|
| InputException | The wav has more channels than are accepted by the system |
| InputException | The sample rate is not supported, must be 8 Khz or 16 Khz |
| InputException | The bits per sample is not supported, must be 16 bits/sample |
| InputException | The wav duration is longer than 30 seconds |
| SignalNoiseRatioException | Noise level exceeded |
| VoiceDurationIsNotEnoughException | Voice duration is less than 3 seconds |
| InvalidChannelException | Invalid specified channel/s |
Response: 500
Server error response.
Content-Type: application/json
| exception | message |
|---|---|
| Exception | Error opening <_io.BytesIO object at 0x7f6baab4dbf8>: File contains data in an unknown format. |
Compute voice identification between a wav input and a list of voice credentials¶
Computes the voice similarity between an input wav and a list of voice credentials, and returns the identification results and the scores.
POST /identification/wav2credentials
Request Body
Request for voice identification with one audio input and a voice credentials list.
| Name | Req. | Type | Description |
|---|---|---|---|
| audio_reference | yes | WAV file | Audio with the reference speaker voice. |
| credentials_list | yes | Dictionar y | List of voice credentials with its corresponding identification tags. Each element on this list shall contain user ID and its credential using a dict with fields "id" and "credential" |
| calibration | no | string | Calibration type to compare credential and audio input. The calibration modes are: ["lossless-audio","telephone-channel","no-calibration" ]. By default "telephone-channel". If SDKs are used for audio capturing, it is necessary to use "lossless-audio". |
| channel | no | int | The channel on which the biometrics operation shall be applied, in case the audio has more than one. (DEFAULT channel = 1) |
Request header
Request for voice authenticity checking.
| Name | Req. | Type | Description |
|---|---|---|---|
| X-Check-Authenticity | No | Header | This header activates the voice authenticity check. If it is present in the query, in the response there will be a authenticity value in range [0,1] indicating if the voice is authentic (close 1), or a spoof attack (close to 0). |
| X-Veridas-RTag | No | Header | This header allows to tagger this query with a personal string. This tag needs to be a ASCII string with a maximum size of 64 characters. |
Example:
https://api-work.eu.veri-das.com/daspeak/v1/identification/wav2credentials
Response: 200
Returns the identification tag with the score and a dictionary with all the tags and scores.
Content-Type: application/json
| Name | Req. | Type | Description |
|---|---|---|---|
| result | yes | Dictionary | Tuple with the identification tag and its score. |
| scores | yes | Dictionary | Results with the identification tags and scores. |
| version | yes | string | API version |
| model | yes | Dictionary | Dictionary with hash and mode fields |
| authenticity | No | number | voice authenticity in range [0,1]. when this number is close to 1 indicates it is authentic and, if it is close to 0, it means spoof. |
Example:
{
"result": {
"id": "User001", "score": 0.90
},
"scores": [
{
"id": "User001", "score": 0.90
},
{
"id": "User002", "score": 0.10
}
],
"model": {
"hash": "1b40a9b479b131ef929",
"mode": "speaker-recognition-8k",
"version": "1.0",
"authenticity": 0.98036
}
}
Response: 400 Request format error.
Content-Type: application/json
| exception | error message |
|---|---|
| InputException | The wav has more channels than are accepted by the system |
| InputException | The sample rate is not supported, must be 8 Khz or 16 Khz |
| InputException | The bits per sample is not supported, must be 16 bits/sample |
| InputException | The wav duration is longer than 30s |
| InvalidAudio | Exceeded Noise Level |
| InvalidAudio | The duration of the voice is not enough |
| InputException | Length of credentials list exceeds the maximum allowed. (Nmax=100). |
| InvalidChannelException | Invalid specified channel/s |
Response: 500
Server error response.
Content-Type: application/json
| exception | message |
|---|---|
| Exception | Error opening <_io.BytesIO object at 0x7f6baab4dbf8>: File contains data in an unknown format. |
Generate a voice biometric credential with a specific model¶
This endpoint is used to generate a voice biometric credential from a given audio input, using the hash of a specific model. The biometric credential size is 1.1 Kbytes.
POST models/{hash}/credential/wav
Parameters
| Name | In | Description | Example |
|---|---|---|---|
| hash | path | A hash given as hex digest, same as returned by | 1b40a9b479b131e7acb |
Example:
*https://api-work.eu.veri-das.com/daspeak/v1/*models/{hash}/credential/wav
Request Body
Request for voice biometric credential generation.
| Name | Req. | Type | Description |
|---|---|---|---|
| audio | yes | WAV file | Audio with the target speaker voice. |
| channel | no | int | The channel on which the biometrics operation shall be applied, in case the audio has more than one. (DEFAULT channel = 1) |
Request header
Request for voice authenticity checking.
| Name | Req. | Type | Description |
|---|---|---|---|
| X-Check-Authenticity | No | Header | This header activates the voice authenticity check. If it is present, in the query will be an authenticity probability [0,1] indicating if the voice is authentic being 1, or if correspond to a spoof attack close to 0. |
| X-Veridas-RTag | No | Header | This header allows to tagger this query with a personal string. This tag needs to be a ASCII string with a maximum size of 64 characters. |
Response: 200
Returns one voice biometric credential for the given audio file, API version,dictionary with hash and mode of the model used to create it.
Content-Type: application/json
| Name | Req. | Type | Description |
|---|---|---|---|
| credential | yes | string | A biometric credential string |
| version | yes | string | API version |
| model | yes | Dictionary | Dictionary with hash and mode fields |
| authenticity | No | number | voice authenticity in range [0,1]. when this number is close to 1 indicates it is authentic and, if it is close to 0, it means spoof. |
Example:
{
"credential": "APUhOWxROgu",
"model": {
"hash": "e7acb9cab797f929e0",
"mode": "speaker-recognition-8k"
},
"version": "1.0",
"authencitity": "0.9830"
}
Response: 400 Request format error.
Content-Type: application/json
| exception | error message |
|---|---|
| InputException | The wav has more channels than are accepted by the system |
| InputException | The sample rate is not supported, must be 8 Khz or 16 Khz |
| InputException | The bits per sample is not supported, must be 16 bits/sample |
| InputException | The wav duration is longer than 30 seconds |
| SignalNoiseRatioException | Noise level exceeded |
| VoiceDurationIsNotEnoughException | Voice duration is less than 3 seconds |
| InvalidChannelException | Invalid specified channel/s |
Response: 500
Server error response.
Content-Type: application/json
| exception | error message |
|---|---|
| Exception | Error opening <_io.BytesIO object at 0x7f6baab4dbf8>: File contains data in an unknown format. |