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:

      - 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.