Skip to content

    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”