API de calidad de audio

Evalúa la calidad percibida de un archivo de audio. Devuelve una puntuación general, detección de voz, nivel de ruido de fondo, volumen e indicadores de saturación o distorsión.

URL base

https://api.genderrecognition.com

Endpoint

POST /v1/audio/quality/api

Encabezados

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

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
file	file	Sí	Archivo de audio que se analizará.

Ejemplo

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

Respuesta

{
  "success": true,
  "quality_score": 82,
  "quality_label": "good",
  "mos_score": 4.1,
  "speech": {
    "detected": true,
    "duration": 4.8,
    "ratio": 92
  },
  "noise": {
    "level": "low",
    "snr_db": 28.4
  },
  "volume": {
    "too_quiet": false,
    "rms_dbfs": -18.2
  },
  "clipping": {
    "detected": false,
    "ratio": 0
  },
  "audio": {
    "duration": 5.2,
    "sample_rate": 44100,
    "channels": 1
  },
  "remainingRequests": 119
}

Campos de respuesta

Campo	Tipo	Descripción
success	boolean	true si el audio se procesó correctamente.
quality_score	integer or null	Calidad perceptual general, de 0 a 100. null si no se detecta voz.
quality_label	string or null	Categoría de calidad de quality_score: excellent (excelente), good (buena), fair (regular) o poor (mala). Es null si quality_score es null.
mos_score	number or null	Puntuación MOS (Mean Opinion Score) estimada, de 1 a 5 (un valor mayor es mejor). Es null si no se detecta voz.
speech.detected	boolean	Indica si se detectó voz en el archivo.
speech.duration	number	Segundos de audio clasificados como voz.
speech.ratio	integer	Porcentaje del archivo que corresponde a voz, de 0 a 100.
noise.level	string or null	Categoría del ruido de fondo: low (bajo), medium (medio) o high (alto). Es null si no se puede medir (por ejemplo, si no hay audio sin voz para comparar).
noise.snr_db	number or null	Relación señal/ruido en dB, que compara la voz con el ruido de fondo. Es null en las mismas condiciones que noise.level.
volume.too_quiet	boolean	true si el audio es demasiado bajo para utilizarlo de forma fiable.
volume.rms_dbfs	number	Volumen en dBFS. 0 es el nivel más alto posible; los valores más negativos indican un volumen más bajo.
clipping.detected	boolean	true si se detectó saturación o distorsión.
clipping.ratio	integer	Porcentaje de muestras de audio afectadas por saturación, de 0 a 100.
audio.duration	number	Duración del archivo enviado, en segundos.
audio.sample_rate	number	Frecuencia de muestreo del audio enviado, en Hz.
audio.channels	number	Número de canales de audio (1 = mono, 2 = estéreo).
remainingRequests	integer	Solicitudes API restantes tras descontar esta solicitud completada correctamente.

quality_score, speech.ratio y clipping.ratio son porcentajes enteros. noise.snr_db y volume.rms_dbfs son valores en decibelios, no porcentajes.

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

Archivo demasiado grande

{ "error": "File too large" }

Campo inesperado

Se devuelve cuando el archivo se envía en un campo distinto de file (por ejemplo, si 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": "Audio quality assessment 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 los archivos de audio en el campo file; no pueden superar los 10 MB.
• La solicitud solo se descuenta cuando la evaluación de calidad termina correctamente.