Saltar al contenido principal

API de género por voz

Detecta el género probable de una persona a partir de un archivo de audio o de una URL de audio.

URL base​

https://api.genderrecognition.com

Elegir un endpoint​

OpciónMétodo y rutaRecomendado para
Análisis estándar por archivoPOST /v1/voice-gender-recognition/apiArchivos sencillos con el comportamiento de análisis estándar.
Análisis estándar por URLPOST /v1/voice-gender-recognition/api/urlUn audio disponible en una URL pública.
V2: análisis de todo el audioPOST /v1/voice-gender-recognition/api/v2Análisis con detección de voz para grabaciones con un solo hablante.
V3: análisis por hablantePOST /v1/voice-gender-recognition/api/v3Llamadas, entrevistas y otras grabaciones con varios hablantes.

El endpoint estándar por URL acepta una URL de audio en JSON. V2 y V3 solo aceptan archivos subidos; no aceptan URL de audio.

Endpoint para archivos​

POST /v1/voice-gender-recognition/api

Encabezados​

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

Cuerpo de la solicitud​

CampoTipoObligatorioDescripción
filefileSíArchivo de audio que se analizará.

Ejemplo​

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

Endpoints de archivo con versiones​

El endpoint estándar para archivos que aparece arriba sigue disponible para las integraciones existentes. V2 y V3 ofrecen otras opciones de análisis de archivos. Aceptan un archivo de audio en el campo multipart file, detectan el habla y pueden devolver unknown cuando no hay suficiente habla utilizable, en lugar de adivinar siempre hombre o mujer.

V2: análisis de todo el audio​

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

V2 comprueba si hay habla humana y después clasifica la grabación completa con el modelo de voz ECAPA-TDNN. Está pensada para grabaciones con un solo hablante. Si hablan varias personas, analiza sus voces juntas; elige V3 si necesitas un resultado centrado en un hablante.

Cada llamada correcta a V2 consume 1 solicitud API.

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

Ejemplo de respuesta cuando se detecta el género:

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

Si no detecta habla humana, V2 devuelve igualmente una respuesta correcta con gender 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álisis por hablante​

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

V3 detecta el habla y usa la diarización para clasificar a un hablante seleccionado. Está diseñada para llamadas, entrevistas y otras grabaciones con varios hablantes. Selecciona al primer hablante, salvo que hable menos de 2 segundos; en ese caso, selecciona al que haya hablado durante más tiempo. Si el hablante seleccionado tiene menos de 1 segundo de habla, el resultado será unknown. V3 tarda más que V2 y realiza una llamada de pago a Deepgram cuando detecta habla.

Cada llamada correcta a V3 consume 2 solicitudes API.

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

Ejemplo de respuesta cuando se detecta el género:

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

Si no hay habla o es demasiado breve para el hablante seleccionado, V3 devuelve una respuesta correcta con gender 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
}

En ambas versiones, confidence es un porcentaje entero de 0 a 100 y remainingRequests muestra el saldo después del cargo. unknown es un resultado correcto, no un error de API. Ambas versiones usan la misma clave API, el campo multipart, el límite de tamaño y los errores comunes de autenticación y validación de archivos que el endpoint estándar.

Endpoint para URL​

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

Encabezados​

apiKey: YOUR_API_KEY
Content-Type: application/json

Cuerpo de la solicitud​

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

Respuesta​

Las solicitudes con archivo devuelven la predicción, el porcentaje de confianza y los metadatos actualizados de la cuota.

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

Las solicitudes con URL devuelven la predicción y los metadatos de la cuota. Las primeras solicitudes lentas también pueden incluir un mensaje info.

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

Errores posibles​

Falta la clave API​

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

Clave API no válida​

{
"error": "Invalid API key"
}

Falta el archivo​

{
"error": "No file uploaded"
}

Tipo de archivo no válido​

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

Solicitud de URL no válida​

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

Falta el encabezado de tipo de contenido JSON​

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

Tipo de contenido JSON no admitido​

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

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

Notas​

  • Las solicitudes con archivo usan datos de formulario multipart.
  • Las solicitudes con URL usan JSON.
  • Envía los archivos de audio en el campo file; no pueden superar los 10 MB.