Audio Quality Checker API

Assess the perceptual quality of an uploaded audio file. Returns an overall quality score, speech detection, background noise level, volume, and clipping/distortion signals.

Base URL

https://api.genderrecognition.com

Endpoint

POST /v1/audio/quality/api

Headers

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

Body

Field	Type	Required	Description
file	file	Yes	Audio file to analyze.

Example

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

Response

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

Response fields

Field	Type	Description
success	boolean	true when the audio was processed successfully.
quality_score	integer or null	Overall perceptual quality, 0-100. null when no speech is detected.
quality_label	string or null	Quality bucket for quality_score: excellent, good, fair, or poor. null when quality_score is null.
mos_score	number or null	Raw predicted Mean Opinion Score, 1-5 (higher is better). null when no speech is detected.
speech.detected	boolean	Whether any speech was found in the file.
speech.duration	number	Seconds of audio classified as speech.
speech.ratio	integer	Percentage of the file that is speech, 0-100.
noise.level	string or null	Background noise bucket: low, medium, or high. null when it can't be measured (for example, no non-speech audio to compare against).
noise.snr_db	number or null	Signal-to-noise ratio in dB, comparing speech to background noise. null under the same conditions as noise.level.
volume.too_quiet	boolean	true when the audio is too quiet to be reliably used.
volume.rms_dbfs	number	Loudness in dBFS. 0 is the loudest possible level; more negative values are quieter.
clipping.detected	boolean	true when clipping/distortion was detected.
clipping.ratio	integer	Percentage of audio samples affected by clipping, 0-100.
audio.duration	number	Duration of the uploaded file in seconds.
audio.sample_rate	number	Sample rate of the uploaded audio, in Hz.
audio.channels	number	Number of audio channels (1 = mono, 2 = stereo).
remainingRequests	integer	API requests remaining after this successful request is deducted.

quality_score, speech.ratio, and clipping.ratio are whole-number percentages. noise.snr_db and volume.rms_dbfs are decibel values, not percentages.

Error cases

Missing API key

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

Invalid API key

{ "error": "Invalid API key" }

Missing file

{ "error": "No file uploaded" }

File too large

{ "error": "File too large" }

Unexpected field

Returned when the file is uploaded under a field name other than file (for example, sending an extra file):

{ "error": "Unexpected field" }

Invalid file type

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

Audio conversion failed

Returned when the file has an allowed extension but ffmpeg cannot convert it (for example, a corrupt or unreadable file):

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

Quota exceeded

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

Processing failed

{ "error": "Audio quality assessment failed" }

Notes

• The backend accepts many common audio formats, including WAV, MP3, M4A, FLAC, OGG, WebM, AAC, Opus, WMA, AMR, 3GP, AIFF, AU, and more, and converts non-WAV files before analysis.
• Audio uploads use the file field and must be 10 MB or smaller.
• A request is deducted only after the quality assessment completes successfully.