API de verificação de locutor

Compare um clipe de referência com um clipe candidato e obtenha uma indicação sobre serem da mesma pessoa, uma pontuação de similaridade e os metadados de áudio dos dois arquivos.

URL base

https://api.genderrecognition.com

Endpoint

POST /v1/speaker-verification/api

Cabeçalhos

apiKey: YOUR_API_KEY
Content-Type: multipart/form-data

Corpo

Campo	Tipo	Obrigatório	Descrição
reference	arquivo	Sim	Voz conhecida usada como referência para a verificação.
candidate	arquivo	Sim	Voz que deseja comparar com a referência.

Exemplo

curl -X POST "https://api.genderrecognition.com/v1/speaker-verification/api" \
  -H "apiKey: YOUR_API_KEY" \
  -F "file=@audio.wav"

Resposta

{
  "success": true,
  "same_speaker": true,
  "similarity": 87,
  "threshold": 70,
  "reference_audio": {
    "duration": 4.8,
    "sample_rate": 16000
  },
  "candidate_audio": {
    "duration": 5.1,
    "sample_rate": 16000
  },
  "remainingRequests": 119
}

Campos da resposta

Campo	Tipo	Descrição
success	booleano	true quando os dois clipes foram processados com sucesso.
same_speaker	booleano	true quando similarity é igual ou superior a threshold, indicando que os clipes parecem ser da mesma pessoa.
similarity	inteiro	Grau de semelhança entre as vozes, de 0 a 100. Valores maiores indicam mais semelhança.
threshold	inteiro	Limite de similaridade para determinar same_speaker, de 0 a 100. Um valor de similarity igual ou maior conta como correspondência.
reference_audio.duration	número	Duração do clipe de referência em segundos após decodificação para comparação.
reference_audio.sample_rate	número	Taxa de amostragem (Hz) para a qual o clipe de referência foi decodificado antes da comparação.
candidate_audio.duration	número	Duração do clipe candidato em segundos após decodificação para comparação.
candidate_audio.sample_rate	número	Taxa de amostragem (Hz) para a qual o clipe candidato foi decodificado antes da comparação.
remainingRequests	inteiro	Solicitações de API restantes após descontar esta solicitação bem-sucedida.

similarity e threshold são porcentagens inteiras, não pontuações brutas.

Casos de erro

Chave de API ausente

{ "error": "API key is required" }

Chave de API inválida

{ "error": "Invalid API key" }

Arquivo ausente(s)

{ "error": "Both reference and candidate files are required" }

Arquivo muito grande

{ "error": "File too large" }

Campo inesperado

Retornado quando um arquivo é enviado em um campo diferente de reference ou candidate (por exemplo, usando file ou enviando um arquivo extra):

{ "error": "Unexpected field" }

Tipo de arquivo inválido

{
  "error": "Invalid file type. Allowed formats: WAV, MP3, FLAC, MP4, OGG, AIFF"
}

Falha na conversão de áudio

Retornado quando o arquivo tem uma extensão permitida, mas o ffmpeg não consegue convertê-lo (por exemplo, se estiver corrompido ou ilegível):

{ "error": "Audio conversion failed: <details>" }

Cota excedida

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded your free tier limit of 50 requests.",
    "detailedMessage": "Insufficient remaining requests. Required: 1, Available: 0",
    "details": {
      "limit": 50,
      "used": 50,
      "reset_date": "2026-07-01T00:00:00.000Z"
    },
    "suggested_action": "Please upgrade to a premium plan to continue using the API."
  }
}

Falha no processamento

{ "error": "Speaker verification failed" }

Observações

• O backend aceita muitos formatos de áudio comuns, incluindo WAV, MP3, M4A, FLAC, OGG, WebM, AAC, Opus, WMA, AMR, 3GP, AIFF, AU e outros, e converte arquivos que não sejam WAV antes da análise.
• Envie os dois arquivos nos campos reference e candidate; cada um deve ter no máximo 10 MB.
• Os clipes de referência e candidato são processados de forma independente e podem ter durações, taxas de amostragem e formatos diferentes.
• A solicitação só é descontada depois que a verificação é concluída com sucesso.