Considerations

The following are some general considerations about this API that must be taken into account before consuming the service.

Authentication

This service sits behind a gateway responsible for authenticating end users and routing requests. The authentication method is API key based.

Versioning

The API version will be included in the URL, after the base url and before the endpoint:

https://<base_url>/<service>/v{number:integer}/<endpoint>

Non-backwards compatible changes will cause a version increment. As of now, the API only supports the v1 version.

Requests

• The multipart/form-data content type must be used on every request.
• The wav files sent to das-Peak must have a format extension (.wav).
• The API is HTTP-based and uses SSL everywhere with valid certificates. For security reasons, customers should never trust das-Peak endpoints exposing invalid certificates.
• Endpoints attempt to conform to the design principles of Representational State Transfer (REST).
• The service includes an /alive endpoint that returns the 200 HTTP status code if the service is up and running. This can be used to check the service’s health.

All responses will be encoded using JSON, regardless of the accepted content-type specified by the client. Responses will return a suitable HTTP status code indicating if the request was successful (200 or 204 if nothing else is returned) or not (any other code). Responses will also include a code field in the JSON body that can provide more information about the concrete error on each case.

In general, successful responses will have the following format: HTTP Status: 200 OK

{
    "data": {
        DATA
    }
}

Or in case of error:

Field	Description
exception	exception that raised the error
error	A message indicating what went wrong

Example:

{
    "exception": "InputException",
    "error": "The wav is not mono."
}

Credentials

This API enables generation of biometric credentials, which are binary strings containing a biometric vector (embedding). Such vectors are a representation of the face used by das-Peak for similarity comparison. Credentials have the following specifications:

• Encoding: das-Peak returns credentials encoded in base64. It is recommended to decode the string to binary before writing it to a persistent storage. Any POST request containing a credential must encoded it in base64 to be understood by das-Peak.
• Length: depends on the biometric model, please, look below for the model specs.

Models

The following models are available:

Model hash (hexadecimal)	Credential length (bits)	sample rate	Released	Expiration
1b40a9b479b131e7acb9cab797f929e28eb5dffac86ce1d71d83c564	11464	8000	2020-Q1	2022-Q1
16dde449bdffa504b805508d58e400b18deb4546219e9aeb63edeed2	3432	8000	2020-Q4	2022-Q4
2b045e0bc0ba5426651d3e4638403da43e5f843afaa32c3fc5773626	3432	8000	2021-Q4	2023-Q4

Audio constraints

• The minimum amount of subject speech is 3s for all endpoints.
• The maximum audio duration to analyze is 30 s.
• Audio format shall be wav (PCM_16 or ULAW) with one channel (mono).
• Each model work better with a sample rate, but all models accept 8000 and 16000 Hz.

Identification

In the identification endpoints /v1/identification/* the maximum of credentials to analyze is set to N=1000.