POST /detect-language

Summary

Detects the spoken language in an uploaded audio file and returns the language name, code, and confidence score.

Intent

Allows callers to identify what language is being spoken in an audio file before deciding how to route or transcribe it, enabling dynamic language-aware pipelines without requiring the caller to know the language in advance.

Parameters

Name	Type	Required	Description
audio_file	file	Yes	The audio file to analyze for language detection. Sent as a multipart/form-data file upload.
encode	boolean	No	Query parameter. When true (default), the audio is pre-processed through FFmpeg before analysis. Set to false only if the audio is already in a format the model can consume directly.

Request example

curl -X POST https://your-whisper-deployment.com/detect-language \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "audio_file=@/path/to/audio.mp3"

Response example

{
  "detected_language": "spanish",
  "language_code": "es",
  "confidence": 0.9742
}

Error cases

• 400 — No audio file is provided in the multipart form body or the field name does not match ‘audio_file’
• 422 — The ‘encode’ query parameter is provided but cannot be parsed as a boolean
• 500 — The audio file is corrupt, unreadable, or in a format FFmpeg cannot decode (when encode=true), causing an internal processing error
• 503 — The ASR model has been unloaded due to idle timeout and is not yet reloaded when the request arrives

Gotchas

• The form field must be named exactly ‘audio_file’ — any other field name will result in a 422 validation error.
• The ‘encode’ parameter defaults to true, meaning FFmpeg processing is applied automatically. Only set encode=false if you are certain your audio is already in a compatible raw format; skipping encoding on an incompatible file will likely cause a server-side error.
• The confidence value is a float between 0 and 1 produced by the model’s internal probability estimate — it is not a percentage and should not be multiplied by 100 without explicit scaling logic.
• The ‘detected_language’ field returns a full lowercase language name (e.g., ‘spanish’), while ‘language_code’ returns the short ISO-like code (e.g., ‘es’). Use ‘language_code’ for programmatic comparisons.
• The model processes the entire uploaded audio to produce a single language detection result. Very long files may increase latency significantly.
• If the deployment is configured with MODEL_IDLE_TIMEOUT, the underlying ASR model may be unloaded after a period of inactivity, causing the first request after idle to fail or be slow while the model reloads.
• Despite auth being marked as not required in the handler, the Authorization Bearer header is listed as the auth mechanism — include it to avoid rejection by any gateway or proxy layer in front of the service.
• Do not set Content-Type manually when using curl with -F flags; the multipart boundary is set automatically by curl and overriding it will break the request.