> 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 vários arquivos de áudio e retorna um modelo de voz (voice template). O modelo de voz é uma cadeia que contém as informações biométricas da voz. Esse modelo pode ser usado para autenticar as vozes no futuro. Os áudios podem estar criptografados ou não, e codificados em base64. O modelo retornado está sempre criptografado e codificado em base64. Aceita 1 áudio, ou de 3 a 5 áudios, para realizar um cadastro independente de texto ou dependente de texto, respectivamente:

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

* **/api/v1/authentication**: Este endpoint é usado para autenticar uma voz. Recebe um arquivo de áudio e um modelo de voz e retorna um valor booleano que indica se a voz pertence à mesma pessoa que a do modelo de voz, assim como uma probabilidade que indica a semelhança entre ambas as vozes. O áudio pode estar criptografado ou não, e codificado em base64. O modelo de voz deve estar criptografado e codificado 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 autenticação 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 requisiçõ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.