> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/sdks/backend-sdk/voice/technical_documentation/api_reference.md).

# Guía de referencia de la API

## 1. Introducción

Este documento incluye la descripción de la API del servicio ofrecido en el producto **FacePhi Voice Service**.

## 2. API REST

El servicio ofrece estos dos endpoints principales:

* **/api/v1/enrollment**: Este endpoint se utiliza para registrar (enroll) una nueva voz. Recibe uno o varios archivos de audio y devuelve una plantilla de voz (voice template). La plantilla de voz es una cadena que contiene la información biométrica de la voz. Esta plantilla puede utilizarse para autenticar las voces en el futuro. Los audios pueden estar cifrados o no, y codificados en base64. La plantilla devuelta siempre está cifrada y codificada en base64. Acepta 1 audio, o de 3 a 5 audios, para realizar un enrolamiento text-independent o text-dependent, respectivamente:

```ascii
      - 1 audio para enrolamiento text-independent.
      - de 3 a 5 audios para enrolamiento text-dependent.
```

* **/api/v1/authentication**: Este endpoint se utiliza para autenticar una voz. Recibe un archivo de audio y una plantilla de voz, y devuelve un valor booleano que indica si la voz pertenece a la misma persona que la de la plantilla de voz, así como una probabilidad que indica la similitud entre ambas voces. El audio puede estar cifrado o no, y codificado en base64. La plantilla de voz debe estar cifrada y codificada en base64.
* **/api/v1/version** y **/api/v1/health**: Endpoints públicos de gestión para obtener la versión del servicio y el estado de disponibilidad (readiness).
* **/api/v1/config**: Endpoint de gestión para obtener o actualizar la configuración pública en tiempo de ejecución. Los ajustes de arranque de la autenticación JWT se ocultan intencionadamente en la respuesta GET y se rechazan en la operación POST.

La autenticación JWT opcional puede habilitarse en el arranque desde `config.json` o mediante las variables de entorno `FACEPHI_VOICE_REST_AUTH_*`. Cuando el JWT está habilitado, `GET /api/v1/version`, `GET /api/v1/health` y las peticiones de preflight `OPTIONS` siguen siendo públicas, mientras que el resto de endpoints requieren un JWT válido mediante `Authorization: Bearer <jwt>` o la cabecera de API key configurada.