> 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/docs.facephi-pt-br/sdks/backend-sdk/voice/technical_documentation/api_reference.md).

# Guia de referência da API

## 1. Introdução

Este documento inclui a descrição da API do serviço oferecido no produto **FacePhi Voice Service**.

## 2. API REST

O serviço oferece estes dois endpoints principais:

* **/api/v1/enrollment**: Este endpoint é usado para registrar (enroll) uma nova voz. Recebe um ou mais arquivos de áudio e devolve uma template de voz (voice template). A template de voz é uma string que contém as informações biométricas da voz. Essa template pode ser usada para autenticar as vozes no futuro. Os áudios podem estar criptografados ou não, e codificados em base64. A template retornada sempre está criptografada e codificada em base64. Aceita 1 áudio, ou de 3 a 5 áudios, para realizar um enrolamento independente de texto ou dependente de texto, respectivamente:

```ascii
      - 1 áudio para enrolamento independente de texto.
      - de 3 a 5 áudios para enrolamento dependente de texto.
```

* **/api/v1/authentication**: Este endpoint é usado para autenticar uma voz. Recebe um arquivo de áudio e uma template de voz, e retorna um valor booleano que indica se a voz pertence à mesma pessoa que a do template de voz, bem como uma probabilidade que indica a similaridade entre ambas as vozes. O áudio pode estar criptografado ou não, e codificado em base64. A template de voz deve estar criptografada e codificada em base64.
* **/api/v1/version** e **/api/v1/health**: Endpoints públicos de gerenciamento para obter a versão do serviço e o estado de disponibilidade (readiness).
* **/api/v1/config**: Endpoint de gerenciamento para obter ou atualizar a configuração pública em tempo de execução. As configurações de inicialização da Authentication JWT são ocultadas intencionalmente na resposta GET e são rejeitadas na operação POST.

A autenticação JWT opcional pode ser habilitada na inicialização a partir de `config.json` ou por meio das variáveis de ambiente `FACEPHI_VOICE_REST_AUTH_*`. Quando o JWT está habilitado, `GET /api/v1/version`, `GET /api/v1/health` e as solicitações de preflight `OPTIONS` continuam sendo públicas, enquanto o restante dos endpoints requer um JWT válido por meio de `Authorization: Bearer <jwt>` ou o cabeçalho de API key configurado.