API de avaliação da qualidade do áudio

Avalie a qualidade perceptiva de um arquivo de áudio enviado. A resposta inclui uma pontuação geral de qualidade, detecção de fala, nível de ruído de fundo, volume e sinais de corte ou distorção.

URL base

https://api.genderrecognition.com

Endpoint

POST /v1/audio/quality/api

Cabeçalhos

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

Corpo

Campo	Tipo	Obrigatório	Descrição
file	arquivo	Sim	Arquivo de áudio a analisar.

Exemplo

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

Resposta

{
  "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 da resposta

Campo	Tipo	Descrição
success	booleano	true quando o áudio foi processado com sucesso.
quality_score	inteiro ou nulo	Qualidade perceptiva geral, de 0 a 100. null quando não há fala detectada.
quality_label	texto ou nulo	Categoria de quality_score: excellent, good, fair ou poor. null quando quality_score é null.
mos_score	número ou nulo	Pontuação bruta estimada na escala Mean Opinion Score, de 1 a 5 (quanto maior, melhor). null quando não há fala detectada.
speech.detected	booleano	Indica se foi encontrada fala no arquivo.
speech.duration	número	Duração, em segundos, do áudio classificado como fala.
speech.ratio	inteiro	Porcentagem do arquivo que contém fala, de 0 a 100.
noise.level	texto ou nulo	Categoria do ruído de fundo: low, medium ou high. null quando não é possível medi-lo (por exemplo, sem áudio sem fala para comparação).
noise.snr_db	número ou nulo	Relação sinal-ruído em dB, comparando a fala com o ruído de fundo. null nas mesmas condições que noise.level.
volume.too_quiet	booleano	true quando o áudio está baixo demais para ser usado com confiança.
volume.rms_dbfs	número	Volume em dBFS. 0 é o nível mais alto possível; valores mais negativos indicam volume mais baixo.
clipping.detected	booleano	true quando foi detectado corte ou distorção.
clipping.ratio	inteiro	Porcentagem de amostras de áudio afetadas por corte, de 0 a 100.
audio.duration	número	Duração do arquivo enviado, em segundos.
audio.sample_rate	número	Taxa de amostragem do áudio enviado, em Hz.
audio.channels	número	Número de canais de áudio (1 = mono, 2 = estéreo).
remainingRequests	inteiro	Solicitações de API restantes após descontar esta solicitação bem-sucedida.

quality_score, speech.ratio, e clipping.ratio são porcentagens inteiras. noise.snr_db e volume.rms_dbfs são valores em decibéis, não porcentagens.

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

Arquivo muito grande

{ "error": "File too large" }

Campo inesperado

Retornado quando o arquivo é enviado em um campo diferente de file (por exemplo, quando um arquivo extra é enviado):

{ "error": "Unexpected field" }

Tipo de arquivo inválido

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

Falha na conversão de áudio

Retornado quando o arquivo tem uma extensão permitida, mas o ffmpeg não consegue convertê-lo (por exemplo, se estiver corrompido ou ilegível):

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

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

Falha no processamento

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

Observações

• O backend aceita muitos formatos de áudio comuns, incluindo WAV, MP3, M4A, FLAC, OGG, WebM, AAC, Opus, WMA, AMR, 3GP, AIFF, AU e outros, e converte arquivos que não sejam WAV antes da análise.
• Envie áudio no campo file; o arquivo deve ter no máximo 10 MB.
• A solicitação só é descontada depois que a avaliação de qualidade é concluída com sucesso.