Skip to content

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": "NoAudioException",
    "error": "No audio input"
}

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.

Audio constraints

  • Audio format: WAV.
  • Number of channels: Mono (single voice) or stereo (specifying the target channel).
  • Audio encoding: PCM16 or G711 (mu-law/a-law). We recommend using the PCM16 encoding, as it will have better performance with the voice biometry engine.
  • Sampling frequency: 8 kHz or 16 kHz.
  • Minimum amount of subject speech: 3s for all endpoints.
  • Maximum audio duration: 30s for all endpoints.

Other formats could be converted to these conditions using the appropriate tools (e.g. ffmpeg). However, VERIDAS cannot guarantee the performance of the voice biometry engine with such samples.

If the audio contains multiple voices, the resulting voice credential will incorporate information from all these voices, which can adversely impact the accuracy of future verification attempts.

Identification

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

API Usage tutorial

The following video shows a short tutorial on how to use the das-Peak API.

Integration Review

The below document summarizes general recommendations/improvements, mandatory checks and several weak points an integration may have, so we strongly suggest paying special attention to them before moving forward as not doing so might cause issues in production.

Veridas Integration Review Document: Download