Speech To Text over WebSockets

Speech to text over WebSocket

Changed on

Open a WebSocket connection to stream audio and receive transcriptions in real-time. Authentication is provided via the standard Authorization: Bearer <API_KEY> header.

Supported engines: Azure, Deepgram, Google, Telnyx, xAI, Speechmatics, Soniox, Parakeet, Humain, Reson8, Cohere.

Connection flow:

  1. Open WebSocket with query parameters specifying engine, input format, and language.
  2. Send binary audio frames (mp3, wav, linear16, or linear32 format, per input_format).
  3. Receive JSON transcript frames with transcript, is_final, and confidence fields.
  4. Close connection when done.
get/speech-to-text/transcription

Request

  • Base URL: wss://api.telnyx.com/v2
  • URL: wss://api.telnyx.com/v2/speech-to-text/transcription
  • Auth: HTTP bearer

Query parameters

transcription_engine'Azure' | 'Deepgram' | 'Google' | 'Telnyx' | 'xAI' | 'Speechmatics' | 'Soniox' | 'Parakeet' | 'Humain' | 'Reson8' | 'Cohere' required

The transcription engine to use for processing the audio stream.

input_format'mp3' | 'wav' | 'linear16' | 'linear32' required

The format of input audio stream.

sample_rateinteger

Audio sample rate in Hz. Required when input_format is a raw encoding (linear16, linear32) — those formats carry no header metadata. Ignored for container formats (mp3, wav), which self-describe their rate. speechmatics/linden-1 accepts only 16000.

languagestring

The language spoken in the audio stream. For cohere/ar-stt, this must be ar or en — unlike other engines, Cohere does not auto-detect the language, and rejects unsupported values including auto; omitting it defaults to ar. For speechmatics/linden-1, omitting it defaults to en; auto, auto_beta, multi, or a language outside its supported list is rejected when the connection is established. speechmatics/linden-1 also accepts en-US, en-GB, en-AU, cmn-Hans, and cmn-Hant, which select the spelling or script variant (en alone uses the default spelling).

interim_resultsboolean

Whether to receive interim transcription results.

'fast'
OR
'deepgram/nova-2' | 'deepgram/nova-3'
OR
'latest_long' | 'latest_short' | 'command_and_search' | 'phone_call' | 'video' | 'default' | 'medical_conversation' | 'medical_dictation'
OR
'openai/whisper-tiny' | 'openai/whisper-large-v3-turbo'
OR
'xai/grok-stt'
OR
'speechmatics/standard' | 'speechmatics/linden-1'

Available Speechmatics models. speechmatics/linden-1 is a preview, vendor-hosted model that accepts only 16 kHz raw audio: set input_format to linear16 or linear32 and sample_rate to 16000. mp3, wav, and other sample rates are not supported for this model.

OR
'soniox/stt-rt-v4'
OR
'nvidia/parakeet-v3' | 'omi-health/omi-med-stt-v1'
OR
'humain/realtime'
OR
'reson8/turns'
OR
'cohere/ar-stt'

The specific model to use within the selected transcription engine.

endpointinginteger

Silence duration (in milliseconds) that triggers end-of-speech detection. When set, the engine uses this value to determine when a speaker has stopped talking. Supported by xAI, Deepgram, Google, Speechmatics (speechmatics/standard only; speechmatics/linden-1 uses fixed service-side voice activity detection and ignores it), and Soniox. Soniox accepts values between 500 and 3000. Other engines may not support this parameter.

redactstring

Enable redaction of sensitive information (e.g., PCI data, SSN) from transcription results. Supported values depend on the transcription engine.

keytermstring

A key term to boost in the transcription. The engine will be more likely to recognize this term. Can be specified multiple times for multiple terms.

keywordsstring

Comma-separated list of keywords to boost in the transcription. The engine will prioritize recognition of these words.

Request body application/octet-stream

string binary required

Binary audio data in mp3, wav, linear16, or linear32 format, per input_format.

Response

WebSocket upgrade successful — this response is not returned directly. See 101 for frame documentation.

Changes

  • 279d149de88fRevision changes
    • info

      added the enum value speechmatics/linden-1 to the property oneOf[speechmatics_models]/ of the query request parameter model

  • 1581f4d44566Revision changes
    • info

      added the enum value omi-health/omi-med-stt-v1 to the property oneOf[parakeet_models]/ of the query request parameter model