API de verificación de hablantes

Compara un audio de referencia con uno candidato. Obtendrás un veredicto sobre si pertenecen a la misma persona, una puntuación de similitud y los metadatos de audio de ambos archivos.

URL base

https://api.genderrecognition.com

Endpoint

POST /v1/speaker-verification/api

Encabezados

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

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
reference	file	Sí	Voz conocida que se usará como referencia.
candidate	file	Sí	Voz que se comparará con la referencia.

Ejemplo

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

Respuesta

{
  "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 de respuesta

Campo	Tipo	Descripción
success	boolean	true si ambos audios se procesaron correctamente.
same_speaker	boolean	true si similarity es igual o superior a threshold, lo que significa que se considera que ambos audios pertenecen a la misma persona.
similarity	integer	Grado de similitud entre ambas voces, de 0 a 100. Cuanto mayor sea el valor, más se parecen.
threshold	integer	Umbral de similitud para determinar same_speaker, de 0 a 100. Un valor de similarity igual o superior a este umbral se considera una coincidencia.
reference_audio.duration	number	Duración del audio de referencia en segundos, una vez decodificado para la comparación.
reference_audio.sample_rate	number	Frecuencia de muestreo (Hz) usada para decodificar el audio de referencia antes de compararlo.
candidate_audio.duration	number	Duración del audio candidato en segundos, una vez decodificado para la comparación.
candidate_audio.sample_rate	number	Frecuencia de muestreo (Hz) usada para decodificar el audio candidato antes de compararlo.
remainingRequests	integer	Solicitudes API restantes tras descontar esta solicitud completada correctamente.

similarity y threshold son porcentajes enteros, no puntuaciones sin convertir.

Errores posibles

Falta la clave API

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

Clave API no válida

{ "error": "Invalid API key" }

Falta el archivo(s)

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

Archivo demasiado grande

{ "error": "File too large" }

Campo inesperado

Se devuelve cuando un archivo se envía en un campo distinto de reference o candidate (por ejemplo, si se usa file o se envía un archivo adicional):

{ "error": "Unexpected field" }

Tipo de archivo no válido

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

Error al convertir el audio

Se devuelve cuando la extensión del archivo está permitida, pero ffmpeg no puede convertirlo (por ejemplo, si está dañado o no se puede leer):

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

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

Error de procesamiento

{ "error": "Speaker verification failed" }

Notas

• El servidor acepta muchos formatos de audio habituales, como WAV, MP3, M4A, FLAC, OGG, WebM, AAC, Opus, WMA, AMR, 3GP, AIFF y AU. Los archivos que no son WAV se convierten antes del análisis.
• Envía ambos archivos en los campos reference y candidate. Cada uno debe pesar 10 MB o menos.
• Los audios de referencia y candidato se procesan por separado, por lo que pueden tener distinta duración, frecuencia de muestreo y formato.
• La solicitud solo se descuenta cuando la verificación termina correctamente.