Skip to content
Whisper ASR Webservice

Search is only available in production builds. Try building and previewing the site to test it out locally.

POST /asr

Summary

Transcribes or translates an uploaded audio file using a Whisper-based ASR model and returns the result as a downloadable text file.

Intent

This endpoint exists to provide automatic speech recognition (ASR) as a service, allowing clients to upload audio files and receive transcriptions or translations in multiple subtitle/text formats, optionally with speaker diarization and word-level timestamps.

Parameters

NameTypeRequiredDescription
audio_filefileYesThe audio file to transcribe. Must be submitted as multipart/form-data.
encodebooleanNoWhether to pre-encode the audio through ffmpeg before processing. Defaults to true. Set to false only if the audio is already in a format directly consumable by the model.
taskstringNoThe task to perform. Allowed values: ‘transcribe’ (default) or ‘translate’. Use ‘translate’ to convert speech in any supported language into English text.
languagestringNoBCP-47 language code of the spoken language in the audio. If omitted, the model will attempt to auto-detect the language.
initial_promptstringNoAn optional text prompt to guide the model’s transcription style, vocabulary, or context. Useful for domain-specific terminology.
word_timestampsbooleanNoWhether to include word-level timestamps in the output. Only available when the ASR engine is ‘faster_whisper’. Defaults to false.
diarizebooleanNoWhether to perform speaker diarization (identify who spoke when). Only available when the ASR engine is ‘whisperx’ and a Hugging Face token is configured. Defaults to false.
min_speakersintegerNoMinimum number of speakers expected in the audio. Only used when diarization is enabled (whisperx engine). Defaults to null (auto-detect).
max_speakersintegerNoMaximum number of speakers expected in the audio. Only used when diarization is enabled (whisperx engine). Defaults to null (auto-detect).
outputstringNoOutput format for the transcription. Allowed values: ‘txt’ (default), ‘vtt’, ‘srt’, ‘tsv’, ‘json’.

Request example

Terminal window
curl -X POST 'https://your-whisper-deployment.com/asr?task=transcribe&language=en&output=srt&word_timestamps=false&encode=true' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -F 'audio_file=@/path/to/your/audio.mp3'

Response example

"1\n00:00:00,000 --> 00:00:03,500\nHello, welcome to the automatic speech recognition demo.\n\n2\n00:00:03,500 --> 00:00:07,200\nThis is a sample transcription returned in SRT format.\n"

Error cases

  • 400 — When the audio_file field is missing from the multipart/form-data body
  • 400 — When an invalid value is provided for the ‘task’ parameter (not ‘transcribe’ or ‘translate’)
  • 400 — When an invalid value is provided for the ‘output’ parameter (not one of txt, vtt, srt, tsv, json)
  • 400 — When an unsupported or invalid language code is provided for the ‘language’ parameter
  • 422 — When a non-boolean value is passed for ‘encode’, ‘word_timestamps’, or ‘diarize’ query parameters
  • 500 — When the ASR model fails to process the audio (e.g., corrupted file, unsupported codec with encode=false, or internal model error)

Gotchas

  • The response is a StreamingResponse with Content-Type ‘text/plain’, not JSON. Do not attempt to parse the response body as JSON unless output=json is specified.
  • The response includes a Content-Disposition header with the original filename and output extension (e.g., ‘attachment; filename=“audio.mp3.srt”’), making it suitable for direct file download.
  • The response also includes an ‘Asr-Engine’ header indicating which backend was used (e.g., ‘faster_whisper’, ‘whisperx’, ‘openai_whisper’). Some parameters like ‘word_timestamps’ and ‘diarize’ are only functional for specific engines.
  • The ‘diarize’ parameter only works when the ASR engine is ‘whisperx’ AND a Hugging Face token (HF_TOKEN) is configured server-side. Sending diarize=true with other engines will not produce an error but will have no effect.
  • The ‘word_timestamps’ parameter is only effective when the ASR engine is ‘faster_whisper’. It is silently ignored by other engines.
  • The ‘min_speakers’ and ‘max_speakers’ parameters are only relevant when using the ‘whisperx’ engine with diarization enabled.
  • Setting encode=false requires the audio to already be in a raw format the model can consume directly. For most use cases, leave encode=true (the default).
  • Auth is not enforced server-side (auth required: false), but the Authorization header is listed as the only permitted auth header if your deployment adds token validation via middleware.
  • The request must use multipart/form-data encoding. Do not send the audio file as a raw binary body or as application/json.
  • If the model has been idle beyond the configured MODEL_IDLE_TIMEOUT, it will be unloaded from memory and must reload on the next request, which may cause a significant delay on the first call after an idle period.