Pular para o conteúdo principal

API de identificação de gênero pela voz

Identifique o gênero provável de quem fala a partir de um áudio enviado ou de uma URL de áudio.

URL base​

https://api.genderrecognition.com

Escolha um endpoint​

OpçãoMétodo e caminhoIndicado para
Análise padrão por arquivoPOST /v1/voice-gender-recognition/apiEnvio de arquivo com o comportamento padrão de análise.
Análise padrão por URLPOST /v1/voice-gender-recognition/api/urlÁudio disponível em uma URL pública.
V2: análise da gravação completaPOST /v1/voice-gender-recognition/api/v2Análise com detecção de fala para gravações com um locutor.
V3: análise por locutorPOST /v1/voice-gender-recognition/api/v3Chamadas, entrevistas e outras gravações com vários locutores.

O endpoint padrão por URL aceita uma URL de áudio em JSON. V2 e V3 aceitam somente arquivos enviados; não aceitam URLs de áudio.

Endpoint de arquivo​

POST /v1/voice-gender-recognition/api

Cabeçalhos​

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

Corpo​

CampoTipoObrigatórioDescrição
filearquivoSimArquivo de áudio a analisar.

Exemplo​

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

Endpoints de arquivo com versões​

O endpoint padrão de arquivo acima continua disponível para integrações existentes. V2 e V3 oferecem outras opções de análise de arquivos. Ambos aceitam um arquivo de áudio no campo multipart file, detectam fala e podem retornar unknown quando não há fala utilizável suficiente, em vez de sempre adivinhar entre masculino e feminino.

V2: análise da gravação completa​

POST /v1/voice-gender-recognition/api/v2

A V2 verifica se há fala humana e depois classifica a gravação inteira com o modelo de voz ECAPA-TDNN. É indicada para gravações com um locutor. Se várias pessoas falarem, as vozes serão analisadas em conjunto; escolha a V3 se precisar de um resultado específico para um locutor.

Cada chamada bem-sucedida da V2 consome 1 solicitação de API.

curl -X POST "https://api.genderrecognition.com/v1/voice-gender-recognition/api/v2" \
-H "apiKey: YOUR_API_KEY" \
-F "file=@audio.wav"

Exemplo de resposta quando o gênero é detectado:

{
"success": true,
"gender": "female",
"confidence": 92,
"remainingRequests": 119
}

Quando não há fala humana detectada, a V2 ainda retorna uma resposta bem-sucedida com gender definido como unknown:

{
"success": true,
"gender": "unknown",
"confidence": 0,
"message": "No clear speech was detected in the audio, so the gender could not be determined.",
"remainingRequests": 119
}

V3: análise por locutor​

POST /v1/voice-gender-recognition/api/v3

A V3 detecta a fala e usa diarização para classificar um locutor selecionado. Foi desenvolvida para chamadas, entrevistas e outras gravações com vários locutores. O primeiro locutor é selecionado, a menos que fale por menos de 2 segundos; nesse caso, é selecionado quem falou por mais tempo. Se o locutor escolhido tiver menos de 1 segundo de fala, o resultado será unknown. A V3 é mais lenta que a V2 e faz uma chamada paga ao Deepgram quando detecta fala.

Cada chamada bem-sucedida da V3 consome 2 solicitações de API.

curl -X POST "https://api.genderrecognition.com/v1/voice-gender-recognition/api/v3" \
-H "apiKey: YOUR_API_KEY" \
-F "file=@audio.wav"

Exemplo de resposta quando o gênero é detectado:

{
"success": true,
"gender": "female",
"confidence": 92,
"remainingRequests": 118
}

Quando não há fala ou ela é curta demais para o locutor selecionado, a V3 retorna uma resposta bem-sucedida com gender definido como unknown:

{
"success": true,
"gender": "unknown",
"confidence": 0,
"message": "Not enough clear speech from a single speaker was detected in the audio, so the gender could not be determined.",
"remainingRequests": 118
}

Nas duas versões, confidence é uma porcentagem inteira de 0 a 100 e remainingRequests mostra o saldo após a cobrança. unknown é um resultado bem-sucedido, não um erro da API. As duas versões usam a mesma chave de API, o campo multipart, o limite de tamanho e os erros comuns de autenticação e validação de arquivo do endpoint padrão.

Endpoint de URL​

POST /v1/voice-gender-recognition/api/url

Cabeçalhos​

apiKey: YOUR_API_KEY
Content-Type: application/json

Corpo​

{
"url": "https://example.com/audio.wav"
}

Resposta​

As solicitações de arquivo retornam a previsão, a confiança em porcentagem e os metadados atualizados da cota.

{
"success": true,
"gender": "male",
"confidence": 97,
"remainingRequests": 2999
}

As solicitações por URL retornam a previsão e os metadados da cota. Solicitações iniciais mais lentas também podem incluir uma mensagem info.

{
"success": true,
"gender": "male",
"remainingRequests": 2999
}

Casos de erro​

Chave de API ausente​

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

Chave de API inválida​

{
"error": "Invalid API key"
}

Arquivo ausente​

{
"error": "No file uploaded"
}

Tipo de arquivo inválido​

{
"error": "Invalid file type. Only audio formats are allowed"
}

Solicitação de URL inválida​

{
"error": "A valid http or https URL is required"
}

Cabeçalho de tipo de conteúdo JSON ausente​

{
"error": "Content-Type header is required. Please set Content-Type: application/json"
}

Tipo de conteúdo JSON não compatível​

{
"error": "Content-Type must be application/json"
}

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

Observações​

  • Solicitações de arquivo usam dados de formulário multipart.
  • Solicitações por URL usam JSON.
  • Envie áudio no campo file; o arquivo deve ter no máximo 10 MB.