POST /asr

Summary

Submits audio data for Automatic Speech Recognition (ASR) and returns a transcription of the spoken content.

Intent

Enables applications to convert spoken audio into text, supporting use cases such as voice commands, transcription services, accessibility features, and voice-driven interfaces.

Parameters

Name	Type	Required	Description
audio	`file	binary	base64 string`
language	string	No	BCP-47 language code (e.g., ‘en-US’, ‘fr-FR’) indicating the spoken language in the audio. If omitted, the server may attempt auto-detection.
model	string	No	Identifier of the ASR model to use for transcription (e.g., ‘base’, ‘large’, ‘whisper-1’). Defaults to the server’s configured default model.
sample_rate	integer	No	Sample rate of the audio in Hz (e.g., 16000, 44100). Some backends require this to match the actual audio sample rate for accurate transcription.
encoding	string	No	Audio encoding format hint (e.g., ‘LINEAR16’, ‘FLAC’, ‘MP3’). May be required if the server cannot infer format from the file extension or MIME type.

Request example

import requests

url = "http://localhost:8000/asr"

with open("audio_sample.wav", "rb") as audio_file:
    response = requests.post(
        url,
        files={"audio": ("audio_sample.wav", audio_file, "audio/wav")},
        data={
            "language": "en-US",
            "model": "base"
        }
    )

if response.status_code == 200:
    result = response.json()
    print("Transcription:", result.get("text"))
else:
    print("Error:", response.status_code, response.text)

Response example

{
  "text": "Hello, this is a sample transcription of the audio file.",
  "language": "en-US",
  "confidence": 0.97,
  "duration": 4.32,
  "segments": [
    {
      "start": 0,
      "end": 2.1,
      "text": "Hello, this is a sample"
    },
    {
      "start": 2.1,
      "end": 4.32,
      "text": "transcription of the audio file."
    }
  ]
}

Error cases

• 400 — when no audio file is provided or the request body is empty
• 415 — when the audio format is unsupported or the MIME type is not accepted
• 422 — when the audio file is corrupt, too short, or contains no detectable speech
• 413 — when the uploaded audio file exceeds the server’s maximum allowed size
• 500 — when the ASR model fails internally or is unavailable

Gotchas

• No authentication is required, meaning this endpoint is publicly accessible — ensure it is not exposed without rate limiting or network-level protection in production.
• Audio sample rate must match the actual recording; mismatches can silently degrade transcription accuracy without returning an error.
• Long audio files may cause request timeouts; consider chunking audio into smaller segments (e.g., 30-second clips) for reliable processing.
• The endpoint likely expects multipart/form-data encoding — sending raw binary as application/octet-stream may not be supported.
• Auto language detection (when ‘language’ is omitted) may be slower and less accurate; always specify the language if known.
• Silence-only or very low-volume audio may return an empty ‘text’ field with a 200 status rather than an error.
• Response field names (e.g., ‘text’, ‘transcript’, ‘transcription’) are not standardized and may vary by implementation — inspect the actual response schema.