Considerations¶
The following are some general considerations about this API that must be taken into account before consuming the service.
Security¶
This service is fortified by a comprehensive security framework designed to protect and manage access to the API. or detailed insights into the security architecture and measures, please consult the Veridas Security Mechanisms Documentation.
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 POST request when a request body is required.
-
Sample files sent to VCSP as part of POST requests must have one of the following content types:
-
audio files:
- audio/wav
- audio/x-wav
- audio/wave
-
image files:
- image/jpg
- image/png
- image/tiff
-
- The API is HTTP-based and uses SSL everywhere with valid certificates. For security reasons, customers should never trust VCSP endpoints exposing invalid certificates.
- Endpoints attempt to conform to the design principles of Representational State Transfer (REST).
- Each request is uniquely identified, which might be helpful to trace support cases. This unique id is returned in the X-Request-Id header. The format of the unique id is a UUID in its hexadecimal form.
- Every timestamp stored in the system is referenced to Zulu timezone (UTC+00). A
Z
character is present at the end of every timestamp field within API response.
Responses¶
- 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 (2xx), a client error occurred (4xx) or a server error occurred (5xx).
- Error responses received as a result of an unsuccessful request will have following format:
Field | Description |
---|---|
error | Error code |
title | Title of the error |
reason | Human readable reason of the error cause |
details | Metadata about the error (optional) |
Example:
{
"error": "audio_not_authentic",
"title": "Audio not authentic",
"reason": "Audio is not authentic",
"details": {
"authenticity_threshold": 0.8,
"authenticity_score": 0.03283321443788212
}
}
Audio constraints¶
- Audio format: WAV.
- Number of channels: Mono (single voice) or stereo (specifying the target channel).
- Audio encoding:
PCM16
orG711 (mu-law/a-law)
. We recommend using thePCM16
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.
Face Images constraints¶
- Supported image formats: JPEG/JFIF, JPEG/EXIF, JPEG Blob, PNG, and TIFF.
- Face must be of at least 80px between eyes to ensure optimum verification and biometric credential computations.
- Face must be of at least 150px width to ensure it can be processed by the face liveness detection systems. To increase accuracy, faces with more than 320px width are recommended.
- Face is expected to be frontal with the camera in the photograph. Less than 30 degrees in head pose rotation (roll, pitch, yaw) is the optimum.
- Face appearance must be with no significant fish-eye distortion.