API reference guide

1. Introduction

This document includes the description of the API of the service offered in the product FacePhi Voice Service.

2. Rest API

The service offers these two main endpoints:

• /api/v1/enrollment: This Endpoint is used to register (enroll) a new voice. It receives one or more audio files and returns a voice template. The voice template is a string that contains the biometric information of the voice. This template can be used to authenticate voices in the future. The audio files can be encrypted or not, and encoded in base64. The returned template is always encrypted and encoded in base64. It accepts 1 audio file, or from 3 to 5 audio files, to perform text-independent or text-dependent enrollment, respectively:

      - 1 audio file for text-independent enrollment.
      - 3 to 5 audio files for text-dependent enrollment.

• /api/v1/authentication: This Endpoint is used to authenticate a voice. It receives an audio file and a voice template, and returns a boolean value indicating whether the voice belongs to the same person as the voice template, as well as a probability indicating the similarity between both voices. The audio can be encrypted or not, and encoded in base64. The voice template must be encrypted and encoded in base64.

• /api/v1/version and /api/v1/health: Public management endpoints to obtain the Version of the service and the availability status (readiness).

• /api/v1/config: Management Endpoint to obtain or update the public configuration at runtime. The JWT Authentication startup settings are intentionally hidden in the GET response and are rejected in the POST operation.

Optional JWT authentication can be enabled at startup from config.json or through the environment variables FACEPHI_VOICE_REST_AUTH_*. When JWT is enabled, GET /api/v1/version, GET /api/v1/health and preflight requests OPTIONS remain public, while the rest of the endpoints require a valid JWT through Authorization: Bearer <jwt> or the configured API key header.