Skip to content

    Development documentation — this describes the current development branch. Documented behavior may not exist in the latest release.

    Transcription and translation

    Transcription and translation

    Section titled “Transcription and translation”

    The server exposes two OpenAI-compatible speech endpoints. Both accept a multipart form upload and return the transcript in the format you request.

    The two endpoints

    Section titled “The two endpoints”
    EndpointTaskLanguage behavior
    POST /v1/audio/transcriptionsTranscribe speech in its original languageAuto-detects, or force with language
    POST /v1/audio/translationsTranslate speech into EnglishAlways auto-detects the source; no language field

    Both endpoints require authentication only when an API_KEY is set (see Configuration overview) and both return 503 while the model is still warming (see Health and readiness).

    Request fields

    Section titled “Request fields”

    transcriptions accepts: file (required), language (optional; omit to auto-detect), prompt (optional decoding hint), response_format, timestamp_granularities[], and model (accepted but ignored). translations accepts file, prompt, and response_format — no language and no timestamp granularities.

    • language forces the source language (for example es). When omitted, the server falls back to DEFAULT_LANGUAGE if configured, otherwise Whisper auto-detects. An unsupported language code returns 400.
    • prompt biases decoding with an initial context string — useful for names, jargon, or acronyms. It maps to Whisper’s initial_prompt.
    • Voice-activity detection filtering is applied by default (ENABLE_VAD_FILTER=true) to skip non-speech.
    • Beam size comes from BEAM_SIZE (default 5).

    Response formats

    Section titled “Response formats”

    response_format accepts five values. The default is json.

    ValueBodyContent type
    textRaw transcripttext/plain
    json{"text": "..."}application/json
    verbose_jsonTask, language, duration, text, segments[], optional words[]application/json
    srtSubRip subtitle text (HH:MM:SS,mmm)text/plain
    vttWebVTT subtitle text (HH:MM:SS.mmm)text/plain

    The web console offers text, json, and verbose_json, and builds .srt / .vtt downloads on the client from verbose_json segments. The server also accepts srt and vtt as response_format values directly.

    Word-level timestamps

    Section titled “Word-level timestamps”

    Add timestamp_granularities[]=word with response_format=verbose_json to get per-word timings:

    Terminal window
    curl -X POST http://localhost:8000/v1/audio/transcriptions \
      -F 'file=@audio.mp3' \
      -F 'response_format=verbose_json' \
      -F 'timestamp_granularities[]=word'

    Words are returned as a flattened top-level words array of {word, start, end, probability} — they are not nested inside segments. Each segment carries id, seek, start, end, text, tokens, temperature, avg_logprob, compression_ratio, no_speech_prob. See the OpenAI-compatible API reference for the full schema.

    Translation

    Section titled “Translation”

    POST /v1/audio/translations takes the same multipart body minus language and translates any supported source language into English:

    Terminal window
    curl -X POST http://localhost:8000/v1/audio/translations \
      -F 'file=@spanish.mp3' -F 'response_format=text'
    Section titled “Related”