---
title: "Speech to text over WebSocket"
method: GET
path: "/speech-to-text/transcription"
tags: ["Speech To Text over WebSockets"]
---

# Speech to text over WebSocket

`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

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.

## Query parameters

- `transcription_engine` 'Azure' | 'Deepgram' | 'Google' | 'Telnyx' | 'xAI' | 'Speechmatics' | 'Soniox' | 'Parakeet' | 'Humain' | 'Reson8' | 'Cohere', required
- `input_format` 'mp3' | 'wav' | 'linear16' | 'linear32', required
- `sample_rate` integer
- `language` string
- `interim_results` boolean
- `model` union
  - 'fast'
  - 'deepgram/nova-2' | 'deepgram/nova-3'
  - 'latest_long' | 'latest_short' | 'command_and_search' | 'phone_call' | 'video' | 'default' | 'medical_conversation' | 'medical_dictation'
  - 'openai/whisper-tiny' | 'openai/whisper-large-v3-turbo'
  - 'xai/grok-stt'
  - '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.
  - 'soniox/stt-rt-v4'
  - 'nvidia/parakeet-v3' | 'omi-health/omi-med-stt-v1'
  - 'humain/realtime'
  - 'reson8/turns'
  - 'cohere/ar-stt'
- `endpointing` integer
- `redact` string
- `keyterm` string
- `keywords` string

## Request body `application/octet-stream`

- string, binary: Binary audio data in mp3, wav, linear16, or linear32 format, per `input_format`.

## Response `200`

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

## Other responses

- `101`: WebSocket connection established. Communication proceeds via binary audio frames (client) and JSON transcript frames (server). **Client → Server:** Binary audio data (mp3, wav, linear16, or linear32, per `input_format`). **Server → Client:** See `TranscriptFrame` and `SttErrorFrame` schemas.
- `400`: Invalid parameters — engine not supported or missing required fields.
- `401`: Authentication failed — missing or invalid Authorization header.
- `422`: Unprocessable entity. The request was well-formed but could not be processed due to semantic errors. This includes validation errors, invalid parameter values and business logic violations.

## Changes

- **2026-10-21** `a2e3f7a0ec7b`: 1 info
  - added the enum value `speechmatics/linden-1` to the property `oneOf[#/components/schemas/speechmatics_models]/` of the `query` request parameter `model`
- **2026-10-15** `a72569d69430`: 1 breaking, 7 info
  - the response property `oneOf[#/components/schemas/TranscriptFrame]/confidence` became nullable for the status `101`
  - added the new optional `query` request parameter `sample_rate`
  - added the new enum value `Cohere` to the `query` request parameter `transcription_engine`
  - added the new enum value `Humain` to the `query` request parameter `transcription_engine`
  - …4 more
- **2026-06-04** `3390803c3bb0`: 1 info
  - endpoint added
- **2026-05-29** `9958429375f5`: 1 breaking
  - api removed without deprecation
- **2026-05-11** `24057b25c3f5`: 1 info
  - added the new enum value `Soniox` to the `query` request parameter `transcription_engine`

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api/changes/speech-to-text/transcription/get.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api/revisions/432d76d72a80?raw)