Telnyx Voice: STT — Full Documentation

Complete page content for STT (Voice section) of the Telnyx developer docs (https://developers.telnyx.com). Root index: https://developers.telnyx.com/llms.txt · Lightweight index for this subsection: https://developers.telnyx.com/development/llms/voice-stt-llms-txt.md

Overview

Source: https://developers.telnyx.com/docs/voice/stt/overview.md

Telnyx STT transcribes audio to text in three ways: Stream audio over a persistent WebSocket connection. Real-time partial and final transcripts. Upload audio files via REST API. OpenAI-compatible endpoint. Enable transcription during live voice calls via Call Control or TeXML.

Quickstart

Source: https://developers.telnyx.com/docs/voice/stt/getting-started.md

Prerequisites

A Telnyx account — sign up here
An API key — create one in the portal

That’s it. No other setup required. Real-time transcription over a persistent connection. Send audio, get partial and final transcripts back as they happen. Install:

pip install "websockets>=14"

main.py:

import asyncio
import json
import urllib.request
import websockets

API_KEY = "YOUR_TELNYX_API_KEY"
STREAM_URL = "https://kexp-mp3-128.streamguys1.com/kexp128.mp3"

async def transcribe():
    url = (
        "wss://api.telnyx.com/v2/speech-to-text/transcription"
        "?transcription_engine=Deepgram"
        "&model=nova-3"
        "&input_format=mp3"
        "&interim_results=true"
    )
    headers = {"Authorization": f"Bearer {API_KEY}"}

    async with websockets.connect(
        url, additional_headers=headers
    ) as ws:
        # Listen for transcripts
        async def listen():
            async for message in ws:
                data = json.loads(message)
                transcript = data.get("transcript", "")
                if not transcript:
                    continue
                prefix = "FINAL" if data.get("is_final") else "partial"
                print(f"[{prefix}] {transcript}")

        listener = asyncio.create_task(listen())

        # Stream audio from KEXP Radio
        req = urllib.request.urlopen(STREAM_URL)
        try:
            while chunk := req.read(4096):
                await ws.send(chunk)
                await asyncio.sleep(0.05)
        except KeyboardInterrupt:
            pass

        await ws.send(json.dumps({"type": "CloseStream"}))
        listener.cancel()

asyncio.run(transcribe())

Run it:

python main.py

Install:

npm install ws

index.js:

const WebSocket = require("ws");
const https = require("https");

const API_KEY = "YOUR_TELNYX_API_KEY";
const STREAM_URL = "https://kexp-mp3-128.streamguys1.com/kexp128.mp3";

const url = new URL("wss://api.telnyx.com/v2/speech-to-text/transcription");
url.searchParams.set("transcription_engine", "Deepgram");
url.searchParams.set("model", "nova-3");
url.searchParams.set("input_format", "mp3");
url.searchParams.set("interim_results", "true");

const ws = new WebSocket(url.toString(), {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

ws.on("open", () => {
  console.log("Connected. Streaming KEXP Radio...\n");

  https.get(STREAM_URL, (stream) => {
    stream.on("data", (chunk) => {
      if (ws.readyState === WebSocket.OPEN) {
        ws.send(chunk);
      }
    });
  });
});

ws.on("message", (data) => {
  const msg = JSON.parse(data);
  const transcript = msg.transcript || "";
  if (!transcript) return;
  const prefix = msg.is_final ? "FINAL" : "partial";
  console.log(`[${prefix}] ${transcript}`);
});

ws.on("error", (err) => console.error("Error:", err.message));

Run it:

node index.js

Example output

Connected. Streaming KEXP Radio...

[partial] the latest news from
[partial] the latest news from the BBC
[FINAL] The latest news from the KEXP Radio.
[partial] tensions continue
[partial] tensions continue to rise in the
[FINAL] Tensions continue to rise in the region as diplomatic talks stall.

Upload an audio file and get the full transcript back. The endpoint is OpenAI SDK compatible — swap base_url and api_key and your existing code works. Install:

pip install openai

main.py:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_TELNYX_API_KEY",
    base_url="https://api.telnyx.com/v2",
)

result = client.audio.transcriptions.create(
    model="openai/whisper-large-v3-turbo",
    file=open("audio.mp3", "rb"),
)

print(result.text)

Run it:

python main.py

Install:

npm install openai

index.js:

const OpenAI = require("openai");
const fs = require("fs");

const client = new OpenAI({
  apiKey: "YOUR_TELNYX_API_KEY",
  baseURL: "https://api.telnyx.com/v2",
});

(async () => {
  const result = await client.audio.transcriptions.create({
    model: "openai/whisper-large-v3-turbo",
    file: fs.createReadStream("audio.mp3"),
  });

  console.log(result.text);
})();

Run it:

node index.js

curl -X POST https://api.telnyx.com/v2/ai/audio/transcriptions \
  -H "Authorization: Bearer YOUR_TELNYX_API_KEY" \
  -F model="openai/whisper-large-v3-turbo" \
  -F file=@audio.mp3

Or transcribe from a URL (no file upload needed):

curl -X POST https://api.telnyx.com/v2/ai/audio/transcriptions \
  -H "Authorization: Bearer YOUR_TELNYX_API_KEY" \
  -F model="openai/whisper-large-v3-turbo" \
  -F file_url="https://example.com/audio.mp3"

Example response

{
  "text": "The latest news from the KEXP Radio. Tensions continue to rise in the region as diplomatic talks stall."
}

For segment- or word-level timestamps, use model="deepgram/nova-3" with response_format=verbose_json. The Whisper models (openai/whisper-large-v3-turbo, openai/whisper-tiny) return text only.

What’s next

Models & Engines — pick the right engine and model for your use case
WebSocket Parameters — interim results, keyword boosting, endpointing, redaction
REST API Parameters — all request body fields for file-based transcription
In-Call Transcription — enable STT during live voice calls

Models

Source: https://developers.telnyx.com/docs/voice/stt/models.md

Comparison

Engine	Model (WebSocket)	Model (REST)	Latency	Languages	Best for
Deepgram	`nova-3`	`deepgram/nova-3`	Low	40+ (reference)	Recommended. Highest English accuracy, diarization, word timestamps
Deepgram	`nova-2`	`deepgram/nova-2`	Low	40+	Legacy — use nova-3 unless you have a specific reason
Deepgram	`flux`	—	Lowest	10 languages	Voice agents — built-in end-of-turn detection (WebSocket only)
Telnyx	`openai/whisper-large-v3-turbo`	`openai/whisper-large-v3-turbo`	Medium	50+ (reference)	Multilingual transcription
Telnyx	`openai/whisper-tiny`	`openai/whisper-tiny`	Low	50+	Lightweight, on-network
Google	`latest_long`	—	Medium	125+ (reference)	Long-form multilingual audio (WebSocket only)
Azure	`azure/fast`	—	Medium	100+ (reference)	Broad language and accent coverage (WebSocket only)
xAI	`xai/grok-stt`	—	Low	25 languages	Grok STT for real-time transcription (WebSocket and Voice API only)
AssemblyAI	`assemblyai/universal-streaming`	—	Low	6 languages	Universal-Streaming for voice agents with low latency and turn detection (WebSocket and Voice API only)
Speechmatics	`speechmatics/standard`	—	Low	17+ languages	High-accuracy real-time transcription with bilingual and multilingual packs (WebSocket and Voice API only)
Soniox	`soniox/stt-rt-v4`	—	Low	Auto-detect	Real-time transcription with interim results and endpointing (WebSocket and Voice API only)
Parakeet	`nvidia/parakeet-v3`	—	—	Auto-detect	Self-hosted multilingual transcription, final transcripts only (WebSocket and Voice API only)

Engine Details

The default WebSocket engine. Best English accuracy and the richest feature set. For REST, you must explicitly set model="deepgram/nova-3" — the REST default is openai/whisper-large-v3-turbo. Models:

nova-3 — Latest and most accurate. Supports diarization, word-level timestamps, smart formatting, numerals, and punctuation via model_config. Use this unless you need the lowest possible latency.
nova-2 — Previous generation. Still supported but nova-3 is better in all benchmarks.
flux — Purpose-built for voice agents. Lowest latency with built-in end-of-turn detection — tells you when the speaker has finished so your agent can respond. WebSocket only.

Languages: 40+ languages across Deepgram models. Nova-3 supports multi mode (10 languages with code-switching). Flux supports English, Spanish, French, German, Hindi, Russian, Portuguese, Japanese, Italian, and Dutch. See Deepgram languages. Telnyx runs Whisper models on-network. Models:

openai/whisper-large-v3-turbo — Multilingual (50+ languages, auto-detected). Returns text only — no timestamps regardless of response format.
openai/whisper-tiny — Lightweight, lowest resource usage.

Languages: 50+ languages, auto-detected. Use auto_detect to skip the language hint. See the Whisper language list. Limitations: No diarization. No word-level timestamps. Google Cloud Speech-to-Text integration. Model: latest_long Languages: 125+ languages/locales. See Google Cloud STT languages. Microsoft Azure Speech Services integration. Model: azure/fast Languages: 100+ languages/locales with strong accent and dialect coverage. See Azure Speech languages. xAI Grok STT integration for real-time transcription. Model: xai/grok-stt Languages: 25 languages, including Arabic, English, French, German, Hindi, Japanese, Korean, Portuguese, Spanish, and Vietnamese. AssemblyAI Universal-Streaming integration for real-time voice agent transcription. Model: assemblyai/universal-streaming Languages: English, Spanish, German, French, Portuguese, and Italian. Speechmatics real-time transcription integration with high accuracy and multilingual support including bilingual packs. Model: speechmatics/standard Languages: English, Spanish, plus bilingual/multilingual packs including Arabic–English, Mandarin–English, English–Malay, English–Tamil, Tagalog, and Spanish–English bilingual. Also supports Basque, Galician, Irish, Maltese, Mongolian, Swahili, Uyghur, and Welsh. Features: Supports interim results (partial transcripts) and graceful CloseStream shutdown. Soniox real-time transcription integration with automatic language detection. Model: soniox/stt-rt-v4 Languages: Automatic detection — no language hint required. Features: Supports interim results (partial transcripts), endpointing, and graceful CloseStream shutdown. Self-hosted NVIDIA Parakeet integration for multilingual transcription with automatic language detection. Model: nvidia/parakeet-v3 Languages: Automatic detection — no language hint required. Features: Final transcripts only — no interim/partial results. Ignores endpointing. Accepts linear16/linear32 (16 kHz) audio only.

How to Choose

Need the highest accuracy for English? → Deepgram nova-3 — best WER (word error rate) across all English variants. Building a voice agent that needs to know when the user stopped talking? → Deepgram flux — lowest latency with built-in end-of-turn detection. Need to transcribe files in 50+ languages? → Telnyx openai/whisper-large-v3-turbo via REST API. Need diarization (who said what)? → Deepgram nova-3 with model_config.diarize: true. Need broad accent/dialect support? → Azure azure/fast — strong coverage across regional accents. Need Grok STT for real-time calls? → xAI xai/grok-stt via WebSocket or Voice API. Need low-latency streaming for voice agents? → AssemblyAI assemblyai/universal-streaming via WebSocket or Voice API. Need high-accuracy multilingual with bilingual packs? → Speechmatics speechmatics/standard via WebSocket or Voice API. Need real-time transcription with automatic language detection? → Soniox soniox/stt-rt-v4 via WebSocket or Voice API. Need self-hosted multilingual transcription with automatic language detection? → Parakeet nvidia/parakeet-v3 via WebSocket or Voice API.

Specifying the Engine and Model

WebSocket — set via query parameters:

wss://api.telnyx.com/v2/speech-to-text/transcription?transcription_engine=Deepgram&model=nova-3

REST API — set via the model body parameter:

curl -X POST https://api.telnyx.com/v2/ai/audio/transcriptions \
  -H "Authorization: Bearer YOUR_TELNYX_API_KEY" \
  -F model="deepgram/nova-3" \
  -F file=@audio.mp3

Migration

Source: https://developers.telnyx.com/docs/voice/stt/migration.md

Most migrations require changing 2–3 lines of code. Pick your current provider below.

WebSocket

- wss://api.deepgram.com/v1/listen?model=nova-2&language=en
- Authorization: Token DEEPGRAM_KEY
+ wss://api.telnyx.com/v2/speech-to-text/transcription?transcription_engine=Deepgram&model=nova-2&language=en
+ Authorization: Bearer TELNYX_KEY

The wire protocol is the same — send binary audio frames, receive JSON transcripts. What changes

	Deepgram	Telnyx
Auth scheme	`Token`	`Bearer`
Engine	implicit	`transcription_engine=Deepgram`
Model name	`nova-2`, `nova-3`, `flux`	`nova-2`, `nova-3`, `flux`

Response field mapping

Deepgram	→ Telnyx
`results.channels[0].alternatives[0].transcript`	`transcript`
`is_final`	`is_final`
`speech_final`	`is_final`

REST

# Before (Deepgram)
curl -X POST https://api.deepgram.com/v1/listen?model=nova-2 \
  -H "Authorization: Token DEEPGRAM_KEY" \
  -H "Content-Type: audio/wav" \
  --data-binary @audio.wav

# After (Telnyx)
curl -X POST https://api.telnyx.com/v2/ai/audio/transcriptions \
  -H "Authorization: Bearer TELNYX_KEY" \
  -F model="deepgram/nova-3" \
  -F file=@audio.wav

What changes

	Deepgram	Telnyx
Auth scheme	`Token`	`Bearer`
Body	raw binary	`multipart/form-data`
Model name	`nova-2`	`deepgram/nova-3`

Response field mapping

Deepgram	→ Telnyx
`results.channels[0].alternatives[0].transcript`	`text`
`results.channels[0].alternatives[0].words`	available via `model_config.diarize` / `model_config.smart_format`

WebSocket

- wss://api.elevenlabs.io/v1/speech-to-text/realtime?model_id=scribe_v1&language_code=en
- xi-api-key: ELEVENLABS_KEY
+ wss://api.telnyx.com/v2/speech-to-text/transcription?transcription_engine=Deepgram&model=nova-3&language=en
+ Authorization: Bearer TELNYX_KEY

The wire protocol is the same — send binary audio frames, receive JSON transcripts. Config mapping

ElevenLabs	Telnyx query parameter
`model_id`	`transcription_engine` + `model`
`language_code`	`language`
`keywords`	`keyterm` (Nova-3/Flux) — see Keyword Boosting

Response field mapping

ElevenLabs	→ Telnyx
`text`	`transcript`
`is_final`	`is_final`

REST

# Before (ElevenLabs)
curl -X POST https://api.elevenlabs.io/v1/speech-to-text \
  -H "xi-api-key: ELEVENLABS_KEY" \
  -F "audio=@audio.mp3" \
  -F "model_id=scribe_v1"

# After (Telnyx)
curl -X POST https://api.telnyx.com/v2/ai/audio/transcriptions \
  -H "Authorization: Bearer TELNYX_KEY" \
  -F model="openai/whisper-large-v3-turbo" \
  -F file=@audio.mp3

What changes

	ElevenLabs	Telnyx
Auth header	`xi-api-key`	`Authorization: Bearer`
File field	`audio`	`file`
Model field	`model_id`	`model`

Response shape: identical. Telnyx returns the same {"text": "..."} shape — no parsing changes needed.

REST

The easiest migration — Telnyx REST is OpenAI SDK compatible. Change the API key and base URL, everything else stays the same.

Python

from openai import OpenAI

client = OpenAI(
-    api_key="sk-OPENAI_KEY",
+    api_key="YOUR_TELNYX_API_KEY",
+    base_url="https://api.telnyx.com/v2",
)

result = client.audio.transcriptions.create(
    model="openai/whisper-large-v3-turbo",
    file=open("audio.mp3", "rb"),
)

JavaScript

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI({
-  apiKey: "sk-OPENAI_KEY",
+  apiKey: "YOUR_TELNYX_API_KEY",
+  baseURL: "https://api.telnyx.com/v2",
});

const result = await client.audio.transcriptions.create({
  model: "openai/whisper-large-v3-turbo",
  file: fs.createReadStream("audio.mp3"),
});

What changes

	OpenAI	Telnyx
`api_key`	`sk-...`	Telnyx API key
`base_url`	(default)	`https://api.telnyx.com/v2`
Method	`client.audio.transcriptions.create(...)`	unchanged
Response	`result.text`	unchanged

Response shape: Telnyx returns the same {"text": "..."} shape — no parsing changes needed for the default json response format. Note on verbose_json: OpenAI’s Whisper API returns segments with timestamps when you set response_format=verbose_json. Telnyx’s Whisper models (openai/whisper-large-v3-turbo, openai/whisper-tiny) return text only — no segments. If you need timestamps, switch to model="deepgram/nova-3" which supports segment- and word-level timestamps via model_config.

WebSocket

Google uses gRPC with protobuf. Telnyx uses WebSocket with JSON — no protobuf compilation, no service account credentials.

# Before (Google Cloud)
from google.cloud import speech

client = speech.SpeechClient()
config = speech.RecognitionConfig(
    encoding=speech.RecognitionConfig.AudioEncoding.LINEAR16,
    sample_rate_hertz=16000,
    language_code="en-US",
    enable_automatic_punctuation=True,
)
streaming_config = speech.StreamingRecognitionConfig(
    config=config,
    interim_results=True,
)
# ... gRPC streaming setup

# After (Telnyx)
wss://api.telnyx.com/v2/speech-to-text/transcription?transcription_engine=Google&language=en-US&interim_results=true&input_format=linear16&sample_rate=16000
Authorization: Bearer TELNYX_KEY

See the Quickstart for full WebSocket code. Config mapping

Google gRPC	Telnyx query parameter
`language_code`	`language`
`encoding`	`input_format`
`sample_rate_hertz`	`sample_rate`
`interim_results`	`interim_results`
`enable_automatic_punctuation`	enabled by default

What you drop: protobuf definitions, gRPC client setup, service account credentials. Response field mapping

Google Cloud	→ Telnyx
`results[0].alternatives[0].transcript`	`transcript`
`results[0].is_final`	`is_final`

WebSocket

AWS Transcribe Streaming uses HTTP/2 with event streams via the amazon-transcribe-streaming-sdk. Telnyx uses a plain WebSocket — no AWS SDK, no SigV4 signing, no IAM credentials.

# Before (AWS) — amazon-transcribe-streaming-sdk
from amazon_transcribe.client import TranscribeStreamingClient
from amazon_transcribe.handlers import TranscriptResultStreamHandler

class Handler(TranscriptResultStreamHandler):
    async def handle_transcript_event(self, event):
        for result in event.transcript.results:
            for alt in result.alternatives:
                print(alt.transcript)

client = TranscribeStreamingClient(region="us-east-1")
stream = await client.start_stream_transcription(
    language_code="en-US",
    media_sample_rate_hz=16000,
    media_encoding="pcm",
)

# Send audio chunks via stream.input_stream.send_audio_event(...)
# Receive results via Handler

# After (Telnyx) — plain WebSocket
wss://api.telnyx.com/v2/speech-to-text/transcription?transcription_engine=Deepgram&model=nova-3&language=en-US&input_format=linear16&sample_rate=16000
Authorization: Bearer TELNYX_KEY

Send binary audio frames, receive JSON transcripts. No AWS SDK, no SigV4 signing, no IAM. See the Quickstart for full code. Config mapping

AWS Transcribe Streaming	Telnyx query parameter
`language_code`	`language`
`media_encoding`	`input_format`
`media_sample_rate_hz`	`sample_rate`
`enable_partial_results_stabilization`	`interim_results`
`vocabulary_name`	`keyterm` (Nova-3/Flux) — see Keyword Boosting

Response field mapping

AWS Transcribe Streaming	→ Telnyx
`transcript.results[].alternatives[].transcript`	`transcript`
`transcript.results[].is_partial`	`is_final` (inverted)

WebSocket

The Azure Speech SDK wraps a region-specific WebSocket with SDK abstractions and event handlers. Telnyx uses a plain WebSocket — no SDK install, no region routing.

# Before (Azure Speech SDK)
import azure.cognitiveservices.speech as speechsdk

speech_config = speechsdk.SpeechConfig(
    subscription="AZURE_KEY",
    region="eastus",
)
speech_config.speech_recognition_language = "en-US"

audio_config = speechsdk.audio.AudioConfig(use_default_microphone=True)
recognizer = speechsdk.SpeechRecognizer(
    speech_config=speech_config,
    audio_config=audio_config,
)

recognizer.recognizing.connect(lambda evt: print(f"partial: {evt.result.text}"))
recognizer.recognized.connect(lambda evt: print(f"FINAL: {evt.result.text}"))
recognizer.start_continuous_recognition()

# After (Telnyx) — plain WebSocket
wss://api.telnyx.com/v2/speech-to-text/transcription?transcription_engine=Azure&language=en-US&interim_results=true
Authorization: Bearer TELNYX_KEY

Send binary audio frames, receive JSON transcripts. No SDK install, no region routing. See the Quickstart for full code. Config mapping

Azure Speech SDK	Telnyx query parameter
`speech_recognition_language`	`language`
`recognizing` event	partial result (`is_final: false`)
`recognized` event	final result (`is_final: true`)
`region`	not needed — single global endpoint

Response field mapping

Azure Speech SDK	→ Telnyx
`evt.result.text` (recognizing/recognized)	`transcript`
`recognizing` event	`is_final: false`
`recognized` event	`is_final: true`

What you drop: Azure Speech SDK install, region routing, event-handler boilerplate, subscription key management.

REST

# Before (Azure)
curl -X POST \
  "https://eastus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US" \
  -H "Ocp-Apim-Subscription-Key: AZURE_KEY" \
  -H "Content-Type: audio/wav" \
  --data-binary @audio.wav

# After (Telnyx)
curl -X POST https://api.telnyx.com/v2/ai/audio/transcriptions \
  -H "Authorization: Bearer TELNYX_KEY" \
  -F model="openai/whisper-large-v3-turbo" \
  -F file=@audio.wav

What changes

	Azure	Telnyx
Auth	`Ocp-Apim-Subscription-Key` header	`Authorization: Bearer`
URL	region-specific	single global endpoint
Body	raw binary	`multipart/form-data`
Language	required query param	auto-detected or optional

Response field mapping

Azure	→ Telnyx
`DisplayText`	`text`
`NBest[0].Lexical`	`text`

WebSocket

Lifecycle

Source: https://developers.telnyx.com/docs/voice/stt/websocket-streaming.md

Real-time speech-to-text over a persistent WebSocket connection. Send audio, receive transcripts.

Endpoint

wss://api.telnyx.com/v2/speech-to-text/transcription

Connection Lifecycle

1. Handshake

The connection starts as an HTTP GET with Upgrade: websocket. The server responds with 101 Switching Protocols, then the connection upgrades to WebSocket frames.

GET /v2/speech-to-text/transcription?transcription_engine=Deepgram&model=nova-3&input_format=wav HTTP/1.1
Host: api.telnyx.com
Upgrade: websocket
Connection: Upgrade
Authorization: Bearer YOUR_API_KEY
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

You can also connect directly to the WebSocket endpoint without an HTTP upgrade:

wss://transcription.telnyx.com/public/speech-to-text/transcription?transcription_engine=Deepgram&model=nova-3&input_format=wav

The same query parameters apply. Once connected, the message protocol is identical. All configuration is set at connect time via query parameters — engine, model, format, language, options. Cannot be changed mid-session. See Parameters for the full list. Invalid parameters return a JSON error and the connection closes.

2. Streaming

Once connected, audio and transcription flow concurrently — no request/response pairing. Client → Server

Frame type	Content
binary	Audio data — raw bytes, chunked. No base64 or JSON wrapping.
text	`{"type": "Finalize"}` — flush buffer, force final transcript (Deepgram only)
text	`{"type": "CloseStream"}` — flush remaining transcription and close the stream gracefully (Deepgram, Speechmatics, Soniox)
text	`{"type": "KeepAlive"}` — reset idle timeout (Deepgram only)

Server → Client

Message	Description
Transcription result	`{"transcript": "...", "is_final": true, "confidence": 0.98}`
Utterance end	`{"transcript": "", "is_final": true, "utterance_end": true}` (Deepgram)
Error	`{"errors": [...]}` — connection closes after

See Messages for the complete wire protocol reference.

Client → Server  binary: audio chunk
Client → Server  binary: audio chunk
Client ← Server  {"transcript":"Hello","is_final":false}
Client → Server  binary: audio chunk
Client ← Server  {"transcript":"Hello, how are you?","is_final":true}

3. Teardown

Send {"type": "CloseStream"} (Deepgram, Speechmatics, and Soniox) to flush remaining audio and close gracefully. The server finishes processing, sends any remaining transcripts, then closes the WebSocket.

Client → Server  {"type":"CloseStream"}
Client ← Server  final transcript
Client ← Server  [connection closed]

For other engines, close the WebSocket connection directly. Dropping the connection without CloseStream works but may lose buffered audio on Deepgram, Speechmatics, and Soniox. See Examples for complete code samples.

Overview

Source: https://developers.telnyx.com/docs/voice/stt/websocket-streaming/parameters.md

All parameters are passed as query string values on the WebSocket URL. Locked at connection time — cannot be changed mid-session. Deepgram, Telnyx, Google, Azure, xAI, AssemblyAI, Speechmatics, Soniox, Parakeet See Engines & Models See Audio Formats Hz. Required for raw encodings (linear16, mulaw, alaw). Ignored for container formats. Invalid value returns error 40005. Language code or auto-detect behavior varies by engine. See Language for details. "true" for partial transcripts. See Interim Results for details. Silence detection in ms for engines that support endpointing. "false" to disable. See Endpointing for details. PII redaction. Deepgram only. See Redaction for details. Comma-separated boost terms. Deepgram Nova-3/Flux. See Keyword Boosting for details. Legacy keyword boosting with intensifiers. Deepgram Nova. See Keyword Boosting for details. Azure Speech Services region. Flux only. Confidence threshold for EndOfTurn events. See End-of-Turn Detection for details. Flux only. Max silence before forcing EndOfTurn. See End-of-Turn Detection for details. Flux only. Speculative EagerEndOfTurn threshold. Disabled by default. See End-of-Turn Detection for details.

Example

wss://api.telnyx.com/v2/speech-to-text/transcription?transcription_engine=Deepgram&model=nova-3&input_format=wav&language=en-US&interim_results=true

Audio Formats

Source: https://developers.telnyx.com/docs/voice/stt/websocket-streaming/parameters/audio-formats.md

Set via the input_format query parameter. Audio is sent as binary WebSocket frames — chunked bytes, no base64, no JSON wrapping. Container formats (mp3, webm, etc.) are self-describing: the server demuxes the byte stream and extracts encoding/sample rate from headers. Raw formats have no metadata, so you must set sample_rate explicitly. Works for both real-time capture (microphone, MediaRecorder, telephony bridge) and file streaming (read a file in chunks, push through the socket).

Browser Capture

Output from MediaRecorder or similar browser APIs. Container headers carry sample rate.

wss://api.telnyx.com/v2/speech-to-text/transcription?input_format=webm_opus

Format	Sample rate	Notes
`webm`	from header	WebM container
`webm_opus`	from header	WebM + Opus. Valid: 8000–48000. Alias: `webm-opus`
`ogg_opus`	from header	Ogg + Opus. Valid: 8000–48000. Alias: `ogg-opus`
`ogg`	from header	Ogg container (Vorbis or other)

Telephony

Codecs from voice networks. Raw frames, sample_rate required.

wss://api.telnyx.com/v2/speech-to-text/transcription?input_format=mulaw&sample_rate=8000

Format	Sample rate	Notes
`mulaw`	any	G.711 µ-law. North America. Default: 8000 Hz.
`alaw`	any	G.711 A-law. EU/international. Default: 8000 Hz.
`g729`	8000	G.729. Fixed.
`amr_nb`	8000	AMR narrowband. Fixed. Alias: `amr-nb`
`amr_wb`	16000	AMR wideband. Fixed. Alias: `amr-wb`
`speex`	8000, 16000, 32000	Google: 16000 only.

Invalid sample rate returns error 40005.

Raw PCM

Uncompressed audio from microphones, processing pipelines, or SDKs. sample_rate required.

wss://api.telnyx.com/v2/speech-to-text/transcription?input_format=linear16&sample_rate=16000

Format	Sample rate	Notes
`linear16`	any	16-bit signed PCM, little-endian (s16le). Default: 16000 Hz.
`linear32`	any	32-bit float PCM, little-endian (f32le). Default: 16000 Hz.
`opus`	8000, 12000, 16000, 24000, 48000	Raw Opus frames, no container. Deepgram also: 44100.

Invalid sample rate returns error 40005.

Recorded File

Pre-recorded files read in chunks and streamed through the socket. Container headers carry sample rate.

wss://api.telnyx.com/v2/speech-to-text/transcription?input_format=mp3

Format	Sample rate	Notes
`mp3`	from header	Default for most engines
`wav`	from header	Uncompressed. Default for Flux model.
`flac`	from header	Lossless compression

Engine Compatibility

Unsupported format/engine combination returns error 40002. Unsupported Flux format returns error 40006. Deepgram has three model generations with different format support. Flux is the most restrictive of Deepgram’s models — it drops mp3, flac, webm_opus, amr_nb, amr_wb, g729, and speex compared to Nova.

Format	Deepgram Nova	Deepgram Flux	Telnyx	Google	Azure	Speechmatics	Soniox	Parakeet
mp3	✓		✓	✓	✓	✓	✓	✓
wav	✓	✓	✓	✓	✓	✓	✓	✓
webm	✓	✓					✓
ogg	✓	✓				✓	✓
flac	✓			✓		✓	✓
ogg_opus	✓	✓		✓
webm_opus	✓			✓
linear16	✓	✓	✓	✓	✓	✓	✓	✓
linear32	✓	✓	✓			✓	✓	✓
mulaw	✓	✓		✓		✓	✓
alaw	✓	✓					✓
opus	✓	✓
amr_nb	✓			✓
amr_wb	✓			✓
g729	✓
speex	✓			✓

Universal formats (all engines and models): wav, linear16.

Engines & Models

Source: https://developers.telnyx.com/docs/voice/stt/websocket-streaming/parameters/engines-and-models.md

Set via transcription_engine and model query parameters.

Engines

Engine	Default model	Other models	Notes
Deepgram	`nova-3`	`nova-2`, `flux`	Default engine. Broadest format support.
Telnyx	`openai/whisper-tiny`	—	On-network, lightweight
Google	`latest_long`	—	Multilingual, long-form
Azure	`azure/fast`	—	Broad language/accent coverage
xAI	`xai/grok-stt`	—	Grok STT for real-time transcription
AssemblyAI	`assemblyai/universal-streaming`	—	Universal-Streaming for low-latency voice agents
Speechmatics	`speechmatics/standard`	—	High-accuracy real-time transcription with multilingual and bilingual packs
Soniox	`soniox/stt-rt-v4`	—	Real-time transcription with automatic language detection
Parakeet	`nvidia/parakeet-v3`	—	Self-hosted multilingual transcription with automatic language detection. Final results only.

Flux Model

Deepgram’s lowest-latency model with built-in end-of-turn detection. Designed for real-time voice agents. See Audio Formats for supported formats.

End-of-Turn Detection

Source: https://developers.telnyx.com/docs/voice/stt/websocket-streaming/parameters/end-of-turn.md

Deepgram Flux only. These parameters return a 400 error on non-Flux models. Flux uses a confidence-based system to decide when a speaker has finished their turn. Confidence threshold (0.5–0.9) for triggering an EndOfTurn event. Higher values require more certainty the speaker is done — fewer false positives but slightly more latency. Lower values respond faster but may cut speakers off mid-thought. Confidence threshold (0.3–0.9) for triggering an early EagerEndOfTurn event. Not set by default — setting it enables eager mode. When fired, your agent can start generating a response speculatively. If the speaker resumes, a TurnResumed event cancels it. Must be ≤ eot_threshold. Lower values = earlier triggers, more false starts. Typical range: 0.3–0.5 for ~150–250 ms latency savings at the cost of ~50–70% more LLM calls. Maximum silence in ms (500–10000) before forcing EndOfTurn regardless of confidence. Resets when speech resumes. Increase for speakers who pause frequently; decrease for rapid-fire Q&A.

Event Flow

Without eager mode (eot_threshold only):

Speech → silence → confidence ≥ eot_threshold → EndOfTurn
Speech → silence → timeout (eot_timeout_ms) → EndOfTurn

With eager mode (eager_eot_threshold set):

Speech → silence → confidence ≥ eager_eot_threshold → EagerEndOfTurn
  → speaker stays silent → confidence ≥ eot_threshold → EndOfTurn
  → speaker resumes → TurnResumed (cancel speculative work)

Configuration Profiles

Default — balanced for general use:

?eot_threshold=0.7&eot_timeout_ms=5000

Low-latency — fast response, more false starts:

?eager_eot_threshold=0.4&eot_threshold=0.7&eot_timeout_ms=6000

High-reliability — fewer interruptions, more latency:

?eot_threshold=0.85&eot_timeout_ms=8000

Language

Source: https://developers.telnyx.com/docs/voice/stt/websocket-streaming/parameters/language.md

BCP-47 language code. Default: en-US.

wss://api.telnyx.com/v2/speech-to-text/transcription?language=es

Auto-Detection

Pass multi to enable automatic language detection. The aliases auto and auto_detect are silently mapped to multi.

?language=multi
?language=auto        # → multi
?language=auto_detect # → multi

Engine Support

Engine	Behavior
Deepgram	BCP-47 codes. `multi` for multi-language mode.
Telnyx	Whisper-based. `auto_detect` disables language hint entirely.
Google	BCP-47 codes.
Azure	BCP-47 codes.
xAI	Language codes such as `en`, `fr`, `de`, and `ja`.
AssemblyAI	Automatic multilingual detection and code switching across supported languages.
Speechmatics	Language codes such as `en`, `es`. Bilingual packs use Telnyx shorthand (e.g. `ar_en`) — mapped internally. Does not support `auto`; defaults to `en` if unrecognized.
Soniox	Automatic language detection. The `language` parameter is ignored — Soniox detects the language from the audio stream.
Parakeet	Automatic multilingual detection. The `language` parameter is ignored — Parakeet always auto-detects.

Supported Languages

For most engines, Telnyx passes the language code directly without validation. The supported set depends on which engine you use. Speechmatics is the exception — Telnyx accepts shorthand codes for bilingual/multilingual packs and maps them to the provider’s language + domain configuration internally.

Engine	Languages	Reference
Deepgram	40+ languages across Deepgram models. Nova-3 supports `multi` (10 languages in code-switching mode). Flux supports English, Spanish, French, German, Hindi, Russian, Portuguese, Japanese, Italian, and Dutch.	Deepgram languages
Telnyx	Whisper-based. 50+ languages. `auto_detect` to skip language hint.	—
Google	125+ languages/locales.	Google Cloud STT languages
Azure	100+ languages/locales.	Azure Speech languages
xAI	25 languages, including Arabic, English, French, German, Hindi, Japanese, Korean, Portuguese, Spanish, and Vietnamese.	xAI Voice API
AssemblyAI	6 languages with native multilingual code switching: English, Spanish, German, French, Portuguese, and Italian.	AssemblyAI supported languages
Speechmatics	17+ languages. Standard codes (`en`, `es`, `cy`, `sw`, etc.) plus Telnyx shorthand for bilingual/multilingual packs (`ar_en`, `cmn_en`, `en_ms`, `en_ta`, `cmn_en_ms_ta`). Telnyx maps these internally to Speechmatics `language` + `domain` params — do not pass them raw to the provider.	Speechmatics languages
Soniox	Automatic language detection — no language hint required. The `language` parameter is ignored.	Soniox docs
Parakeet	Automatic multilingual detection — no language hint required. The `language` parameter is ignored.	—

Common Codes

Code	Language
`en` or `en-US`	English (US)
`en-GB`	English (UK)
`es`	Spanish
`fr`	French
`de`	German
`pt-BR`	Portuguese (Brazil)
`it`	Italian
`ja`	Japanese
`zh`	Chinese (Mandarin)
`hi`	Hindi
`ar`	Arabic
`ko`	Korean
`multi`	Multi-language / auto-detect (Deepgram)

Interim Results

Source: https://developers.telnyx.com/docs/voice/stt/websocket-streaming/parameters/interim-results.md

Deepgram, Speechmatics, and Soniox. Other engines ignore this parameter. Controls whether the server sends partial (non-final) transcripts as speech is processed.

wss://api.telnyx.com/v2/speech-to-text/transcription?interim_results=true

Default: false. Pass "true" as a string. interim_results=false (default) — Server sends only final transcripts. Each message has is_final: true. Lower message volume, higher latency per result.

{"transcript": "Hello, how are you?", "is_final": true, "confidence": 0.98}

interim_results=true — Server sends evolving partial transcripts as audio is processed, followed by a final. Partials have is_final: false and are replaced by the next message.

{"transcript": "Hello", "is_final": false, "confidence": 0.0}
{"transcript": "Hello, how", "is_final": false, "confidence": 0.0}
{"transcript": "Hello, how are you?", "is_final": true, "confidence": 0.98}

Partial transcripts have confidence: 0.0 — confidence is only meaningful on final results.

Endpointing

Source: https://developers.telnyx.com/docs/voice/stt/websocket-streaming/parameters/endpointing.md

Deepgram, xAI, Google, Speechmatics, and Soniox. Other engines ignore this parameter. Controls how long the engine waits after silence before finalizing an utterance. Soniox has a different valid range. When transcription_engine=Soniox, this parameter maps to max_endpoint_delay_ms and must be between 500 and 3000 ms. Values outside that range are rejected. The default (100 ms) and the low-value examples below apply to Deepgram, xAI, Google, and Speechmatics only.

# Deepgram / xAI / Google / Speechmatics
wss://api.telnyx.com/v2/speech-to-text/transcription?endpointing=300

# Soniox (500–3000 ms)
wss://api.telnyx.com/v2/speech-to-text/transcription?transcription_engine=Soniox&endpointing=1000

Default: 100 ms (not applicable to Soniox — Soniox endpointing is disabled unless a value in the 500–3000 ms range is provided).

Values

Value	Behavior
Integer (ms)	Finalize after this many ms of silence. Lower = faster but more splits.
`"false"`	Disable endpointing entirely. No automatic utterance boundaries.

Trade-offs

Low values (50–100 ms) — Fast response. Utterances may split mid-sentence on short pauses. (Deepgram, xAI, Google, Speechmatics only — below Soniox minimum.) High values (300–1000 ms) — More complete sentences. Higher latency before finalization. Soniox range (500–3000 ms) — Minimum 500 ms. Use 500–800 ms for responsive turn detection, 1000–3000 ms for longer utterances with natural pauses. Disabled ("false") — No automatic splits. Use Finalize control messages to manually trigger boundaries, or rely on CloseStream for a single final transcript.

Interaction With Utterance End

When endpointing triggers, Deepgram sends the final transcript followed by an utterance end event (if utterance_end_ms is configured server-side — currently 1000 ms).

{"transcript": "Hello, how are you?", "is_final": true}
{"transcript": "", "is_final": true, "utterance_end": true}

The utterance end marker signals “this speaker turn is done.” See Messages for details.

Keyword Boosting

Source: https://developers.telnyx.com/docs/voice/stt/websocket-streaming/parameters/keyword-boosting.md

Deepgram only. Other engines ignore these parameters. Two parameters control keyword boosting. They target different Deepgram model generations.

`keyterm` — Nova-3 and Flux

Comma-separated list of terms to boost. Simple — no intensifiers.

?keyterm=Telnyx,WebRTC,SIP

Deepgram Nova-3 and Flux only. Ignored on older models.

`keywords` — Nova (Legacy)

Terms with optional intensity scores. Format: keyword:intensifier.

?keywords=Telnyx:2

Deepgram Nova only. Not supported on Flux (silently ignored).

Which To Use

Model	Parameter
Flux	`keyterm`
Nova-3	`keyterm`
Nova	`keywords`
Nova-2	`keywords`

Examples

Boost multiple terms on Nova-3:

?transcription_engine=Deepgram&model=nova-3&keyterm=Telnyx,SIP,RTP,WebRTC

Boost with intensifiers on legacy Nova:

?transcription_engine=Deepgram&model=nova&keywords=Telnyx:2&keywords=telephony:1

Redaction

Source: https://developers.telnyx.com/docs/voice/stt/websocket-streaming/parameters/redaction.md

Deepgram only. Other engines ignore this parameter. Replaces sensitive data in transcripts with placeholder text.

wss://api.telnyx.com/v2/speech-to-text/transcription?redact=pci

Values

Value	Redacts
`pci`	Credit card numbers
`ssn`	Social Security numbers
`numbers`	All numeric sequences

Multiple values can be passed as comma-separated:

?redact=pci,ssn

Output

Redacted content is replaced in the transcript text. The exact replacement format depends on the Deepgram model.

{"transcript": "My card number is [REDACTED]", "is_final": true}

Redaction applies to final and interim results. There is no way to get the un-redacted version once redaction is enabled for a session.

Messages

Source: https://developers.telnyx.com/docs/voice/stt/websocket-streaming/responses.md

The WebSocket carries two frame types: binary frames (audio) from client to server, and JSON text frames in both directions.

Client → Server

Audio Data

Binary WebSocket frames containing raw audio bytes. No base64, no JSON wrapping. Recommended chunk size: 2048–8192 bytes. Smaller chunks reduce latency; larger chunks reduce round trips.

[binary frame: audio bytes]

Control Messages

JSON text frames with a type field.

Finalize

{"type": "Finalize"}

CloseStream

{"type": "CloseStream"}

KeepAlive

{"type": "KeepAlive"}

Type	Effect	Engine support
`Finalize`	Flush audio buffer, force a final transcript	Deepgram only
`CloseStream`	End session, close connection gracefully	Deepgram, Speechmatics, Soniox
`KeepAlive`	Reset idle timeout	Deepgram only

Unknown text frames are silently ignored.

Server → Client

All server messages are JSON text frames.

Transcription Result

Emitted for each recognized speech segment (partial or final).

{
  "transcript": "Hello, how are you today?",
  "is_final": true,
  "speech_final": true,
  "confidence": 0.98
}

Field	Type	Present	Description
`transcript`	string	Always	Transcribed text
`is_final`	boolean	Always	`true` = finalized segment. `false` = interim (may revise).
`speech_final`	boolean	Deepgram	`true` = speaker stopped talking
`confidence`	float	When available	0.0–1.0 confidence score
`utterance_end`	boolean	Deepgram	`true` = silence-triggered utterance boundary

Utterance End

Emitted on speaker pause (Deepgram). Empty transcript, is_final: true.

{
  "transcript": "",
  "is_final": true,
  "utterance_end": true
}

Error

Emitted on validation or connection errors. Connection closes shortly after.

{
  "errors": [
    {
      "code": "40002",
      "title": "Unsupported format",
      "detail": "Format 'flac' is not supported by engine 'Azure'",
      "source": {"parameter": "input_format"}
    }
  ]
}

Field	Type	Description
`errors`	array	One or more error objects
`errors[].code`	string	Error code (see Errors)
`errors[].title`	string	Short description
`errors[].detail`	string	Human-readable explanation
`errors[].source.parameter`	string	Query parameter that caused the error

Message Flow

interim_results=false (default) — server sends only final transcripts:

Client:  [binary audio frames]
Server:  {"transcript": "Hello, how are you today?", "is_final": true, "speech_final": true, "confidence": 0.98}
Client:  [binary audio frames]
Server:  {"transcript": "I'm doing well.", "is_final": true, "speech_final": true, "confidence": 0.95}
Client:  {"type": "CloseStream"}
         [connection closed]

interim_results=true — server sends partials, then final:

Client:  [binary audio frames]
Server:  {"transcript": "Hello", "is_final": false, "speech_final": false}
Server:  {"transcript": "Hello, how are", "is_final": false, "speech_final": false}
Server:  {"transcript": "Hello, how are you today?", "is_final": true, "speech_final": true, "confidence": 0.98}

Partials are best-effort and may revise. Only is_final: true results are stable.

Errors

Source: https://developers.telnyx.com/docs/voice/stt/websocket-streaming/errors.md

If you send an invalid parameter (unsupported engine, format, or format/engine combination), the server responds with a JSON error and closes the connection.

Error Response Format

{
  "errors": [{
    "code": "40001",
    "title": "Invalid Parameter",
    "detail": "Unsupported input_format 'aac'. Supported formats: mp3, wav, webm, ogg, flac, ogg_opus, webm_opus, linear16, linear32, mulaw, alaw, opus, amr_nb, amr_wb, g729, speex",
    "source": { "parameter": "input_format" }
  }]
}

Error Codes

Code	Meaning
`40001`	Invalid `input_format` value
`40002`	Format not supported by the chosen engine
`40003`	`sample_rate` required but missing (raw encoding or Google with non-WAV/FLAC)
`40004`	`sample_rate` is not a valid positive integer
`40005`	Invalid sample rate for the codec (e.g., `amr_nb` only supports 8000)
`40006`	Format not supported by Flux model
`40007`	Invalid `transcription_engine` value

Examples

Source: https://developers.telnyx.com/docs/voice/stt/websocket-streaming/examples.md

Stream a WAV file and print transcripts.

Python

import asyncio
import json
import websockets

API_KEY = "YOUR_API_KEY"
AUDIO_FILE = "audio.wav"

async def transcribe():
    url = (
        "wss://api.telnyx.com/v2/speech-to-text/transcription"
        "?transcription_engine=Deepgram"
        "&model=nova-3"
        "&input_format=wav"
        "&interim_results=true"
    )
    headers = {"Authorization": f"Bearer {API_KEY}"}

    async with websockets.connect(url, extra_headers=headers) as ws:
        async def listen():
            async for message in ws:
                data = json.loads(message)
                prefix = "FINAL" if data.get("is_final") else "partial"
                print(f"[{prefix}] {data.get('transcript', '')}")

        listener = asyncio.create_task(listen())

        with open(AUDIO_FILE, "rb") as f:
            while chunk := f.read(4096):
                await ws.send(chunk)
                await asyncio.sleep(0.05)

        await asyncio.sleep(3)
        await ws.send(json.dumps({"type": "CloseStream"}))
        listener.cancel()

asyncio.run(transcribe())

JavaScript

const WebSocket = require("ws");
const fs = require("fs");

const API_KEY = "YOUR_API_KEY";
const AUDIO_FILE = "audio.wav";

const url = new URL("wss://api.telnyx.com/v2/speech-to-text/transcription");
url.searchParams.set("transcription_engine", "Deepgram");
url.searchParams.set("model", "nova-3");
url.searchParams.set("input_format", "wav");
url.searchParams.set("interim_results", "true");

const ws = new WebSocket(url.toString(), {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

ws.on("open", () => {
  const audio = fs.readFileSync(AUDIO_FILE);
  for (let i = 0; i < audio.length; i += 4096) {
    ws.send(audio.slice(i, i + 4096));
  }
  setTimeout(() => {
    ws.send(JSON.stringify({ type: "CloseStream" }));
    ws.close();
  }, 3000);
});

ws.on("message", (data) => {
  const msg = JSON.parse(data);
  const prefix = msg.is_final ? "FINAL" : "partial";
  console.log(`[${prefix}] ${msg.transcript || ""}`);
});

ws.on("error", (err) => console.error("Error:", err.message));

Production Patterns

Source: https://developers.telnyx.com/docs/voice/stt/websocket-streaming/production-patterns.md

Use these patterns when running the standalone WebSocket STT endpoint in production.

Connection Recovery

Treat the WebSocket session as disposable. Reconnect on network failure, server close, idle timeout, and process restart.

Event	Action
Connection fails before `open`	Retry with backoff. Do not send audio until the connection is open.
Connection closes unexpectedly	Stop sending audio, preserve buffered audio, reconnect, then resume streaming.
Error message received	Log `errors[].code`, `errors[].title`, and `errors[].source.parameter`. Reconnect only after fixing parameter errors.
Graceful shutdown	Send `{"type": "CloseStream"}` and wait for final transcripts before closing the socket.

Set all query parameters on every reconnect. STT configuration cannot be changed mid-session.

Backoff

Use bounded exponential backoff with jitter.

Attempt	Base delay
1	250 ms
2	500 ms
3	1 s
4	2 s
5+	5 s max

Add random jitter of 0-500 ms per attempt. Reset the attempt counter after a stable connection. Do not retry immediately on authentication or validation errors. Fix the API key, query parameters, engine, model, or format first.

Partials

Enable interim_results=true when the application needs live captions or low-latency UI updates.

Message	Handling
`is_final: false`	Display as temporary text. Replace it when a newer partial arrives. Do not persist it as final transcript.
`is_final: true`	Commit to the transcript. Do not replace it with later partials.
`utterance_end: true`	Treat as a segment boundary. Do not render an empty transcript as text.

Store final transcript segments separately from the current partial. This prevents duplicate text when a final result arrives after one or more interim results.

Audio Buffering

Buffer audio at the producer boundary, not inside the WebSocket send loop.

Control	Recommendation
Chunk size	Send 2048-8192 byte binary frames.
Queue size	Set a maximum buffered duration, such as 5-10 seconds.
Backpressure	Pause or drop low-priority audio when the queue is full.
Reconnect	Keep a short rolling buffer only if retranscription after reconnect is required.

Avoid unbounded queues. A slow or disconnected socket should not grow memory usage indefinitely. For live audio, prefer dropping stale buffered audio over sending it late. Late audio increases transcript delay and can make captions appear out of sync.

Keepalive

For Deepgram sessions, send {"type": "KeepAlive"} during long silence periods. Keep sending audio as binary frames when audio is available. For other engines, use the WebSocket client’s ping/pong support when available and reconnect on missed heartbeats.

Monitoring

Track connection, latency, transcript, and buffer metrics.

Metric	Purpose
Connection attempts	Detect retry loops and regional network issues.
Connection duration	Detect unstable sessions and idle timeout patterns.
Close code and reason	Separate expected closes from failures.
Error codes	Identify invalid parameters and engine compatibility issues.
Audio queue depth	Detect send-loop backpressure.
Partial-to-final latency	Measure caption freshness.
Final transcript count	Detect stalled recognition.
Empty final count	Detect silence segmentation behavior.

Log the selected transcription_engine, model, input_format, sample_rate, and interim_results value with each session. Redact API keys and user audio.

Shutdown

Use graceful shutdown for planned stops.

Drain the audio queue.
Send {"type": "CloseStream"}.
Wait for final transcript messages.
Close the WebSocket.

Set a shutdown timeout. If final messages do not arrive before the timeout, close the socket and mark the transcript as incomplete.

Pricing

Source: https://developers.telnyx.com/docs/voice/stt/websocket-streaming/pricing.md

Pricing for WebSocket STT varies by engine and model. Contact sales or check the pricing page for current rates.

REST API

Overview

Source: https://developers.telnyx.com/docs/voice/stt/rest-api.md

POST /v2/ai/audio/transcriptions Synchronous file transcription. Upload audio or pass a URL, get text back.

Feature Support

If you’re coming from alternative providers:

Feature	Status
OpenAI SDK compatible	Yes — swap `base_url` and `api_key`, existing code works
Multi-engine selection	Yes — 3 models behind one endpoint
File upload	Yes
URL transcription	Yes (`file_url`)
Timestamps (segment)	Yes (`verbose_json`)
Timestamps (word-level)	Deepgram only (via `model_config`)
Diarization	Deepgram only (via `model_config`)
Smart formatting	Deepgram only (via `model_config`)
Multilingual	Model-dependent — whisper-turbo: 80+ languages, whisper-tiny: 50+ languages, Deepgram models support language coverage based on the selected model
Async / webhooks	No
Multichannel	No (forced mono)
Export formats (SRT/VTT)	No
Audio event tagging	No
YouTube/TikTok URL	No
Transcript retrieval	No
File size limit	100 MB

Quick Start

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_TELNYX_API_KEY",
    base_url="https://api.telnyx.com/v2",
)

result = client.audio.transcriptions.create(
    model="openai/whisper-large-v3-turbo",
    file=open("audio.mp3", "rb"),
)

JavaScript

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI({
  apiKey: "YOUR_TELNYX_API_KEY",
  baseURL: "https://api.telnyx.com/v2",
});

const result = await client.audio.transcriptions.create({
  model: "openai/whisper-large-v3-turbo",
  file: fs.createReadStream("audio.mp3"),
});

Overview

Source: https://developers.telnyx.com/docs/voice/stt/rest-api/parameters.md

All parameters are sent as multipart/form-data. Model to use for transcription. See Models for details. Values: openai/whisper-large-v3-turbo (default), openai/whisper-tiny, deepgram/nova-3 Audio file to transcribe. Mutually exclusive with file_url. See Audio Formats for supported formats, size limits, and per-model restrictions. Publicly accessible URL to an audio file. Mutually exclusive with file. See Audio Formats for details on how file and file_url differ. Language hint. Behavior varies by model — see Language. Output shape. See Response Format. Values: json (default), verbose_json Timestamp detail level. Only valid with response_format=verbose_json — returns 400 otherwise. Values: segment Deepgram-specific options. Only valid with deepgram/nova-3 — returns 400 for other models. See Model Config.

Models

Source: https://developers.telnyx.com/docs/voice/stt/rest-api/parameters/models.md

Your choice of model determines which audio formats are accepted, what language values are valid, and what response fields are available.

	`openai/whisper-large-v3-turbo`	`openai/whisper-tiny`	`deepgram/nova-3`
Default	Yes
Audio formats	All 10	All 10	mp3, wav only
Language	80+ languages, auto-detected	50+ languages, auto-detected	English variants only (`en`, `en-US`, `en-GB`, `en-AU`, `en-NZ`, `en-IN`)
Timestamps	No	No	Word-level (via `model_config`)
Diarization	No	No	Yes (via `model_config`)
Smart formatting	No	No	Yes (via `model_config`)
`model_config`	Returns 400	Returns 400	Deepgram pass-through

`openai/whisper-large-v3-turbo`

Default model. Multilingual. Auto-detected if language omitted. See Whisper docs for the full language list. Returns text only — no timestamps regardless of response_format.

`openai/whisper-tiny`

Lightweight, lowest resource usage. Multilingual (50+ languages, auto-detected). Returns text only — no timestamps.

`deepgram/nova-3`

Highest accuracy for English. Advanced features (diarization, word timestamps, smart formatting, numerals, punctuation) available via model_config. Defaults language to en if omitted. Can also set language inside model_config — top-level field takes precedence. See Deepgram language docs for details.

Audio Formats

Source: https://developers.telnyx.com/docs/voice/stt/rest-api/parameters/audio-formats.md

Applies to both file (multipart upload) and file_url (URL download).

Common

Max size: 100 MB
Processing: All audio is decoded, resampled to 16kHz, and mixed to mono via ffmpeg before transcription. Container format doesn’t matter as long as ffmpeg can decode it — the validated extension list is the actual restriction.

Supported Formats

Format	`whisper-turbo`	`whisper-tiny`	`deepgram/nova-3`
flac	Yes	Yes	No
m4a	Yes	Yes	No
mp3	Yes	Yes	Yes
mp4	Yes	Yes	No
mpeg	Yes	Yes	No
mpga	Yes	Yes	No
oga	Yes	Yes	No
ogg	Yes	Yes	No
wav	Yes	Yes	Yes
webm	Yes	Yes	No

`file` vs `file_url`

	`file`	`file_url`
Delivery	Multipart upload in request body	Server downloads from URL before transcription
Timeout	Request timeout	15s download timeout
Auth	N/A	URL must be publicly accessible (no auth headers forwarded)
Validation	Same format and size checks	Same format and size checks

One of file or file_url is required. Sending both returns 400.

Model Config

Source: https://developers.telnyx.com/docs/voice/stt/rest-api/parameters/model-config.md

Deepgram only. Returns 400 if used with other models. Pass-through to Deepgram’s pre-recorded API query parameters. Every key-value pair in model_config is forwarded directly — Telnyx does not validate individual options.

Commonly Used Options

Option	Type	Description
`smart_format`	boolean	Capitalization, punctuation, dates, numbers, currency
`punctuate`	boolean	Add punctuation
`diarize`	boolean	Speaker identification. Adds `speakers` array to `verbose_json` segments.
`utterance`	boolean	Segment transcript into utterances
`numerals`	boolean	Convert spoken numbers to digits
`language`	string	Override language. Top-level `language` param takes precedence.

Example

curl -X POST https://api.telnyx.com/v2/ai/audio/transcriptions \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -F "file=@call-recording.mp3" \
  -F "model=deepgram/nova-3" \
  -F "response_format=verbose_json" \
  -F 'model_config={"smart_format": true, "diarize": true, "punctuate": true}'

model_config can be sent as a JSON string in the multipart form field. The server parses it before forwarding.

Unvalidated Pass-Through

Any Deepgram query parameter can be passed. If Deepgram adds new options, they work immediately without a Telnyx API update. Conversely, invalid keys are forwarded and may cause Deepgram to return an error. Refer to Deepgram’s API reference for the full list of supported parameters.

Response Format

Source: https://developers.telnyx.com/docs/voice/stt/rest-api/parameters/response.md

Controlled by the response_format parameter.

`json` (Default)

Text only.

{
  "text": "The quick brown fox jumps over the lazy dog."
}

`verbose_json`

Adds duration (seconds) and timestamped segments — only when using deepgram/nova-3. The Whisper models (openai/whisper-large-v3-turbo, openai/whisper-tiny) return text only regardless of response_format. See the Timestamp Availability table below. Example response with model=deepgram/nova-3:

{
  "text": "The quick brown fox jumps over the lazy dog.",
  "duration": 3.42,
  "segments": [
    {
      "id": 0,
      "text": "The quick brown fox jumps over the lazy dog.",
      "start": 0.0,
      "end": 3.42
    }
  ]
}

Set timestamp_granularities[]=segment alongside response_format=verbose_json. Using timestamp_granularities without verbose_json returns 400.

Segment Fields

Field	Type	Description
`id`	integer	Zero-indexed segment number
`text`	string	Segment transcript
`start`	float	Start time in seconds
`end`	float	End time in seconds
`words`	array	Word-level timestamps (present when the backend provides them — Deepgram only)
`speakers`	array	Speaker labels (present when `diarize=true` in `model_config` — Deepgram only)

Timestamp Availability by Model

Model	`verbose_json` timestamps
`openai/whisper-large-v3-turbo`	No timestamps — backend returns text only
`openai/whisper-tiny`	No timestamps — backend returns text only
`deepgram/nova-3`	Segment-level + word-level (from Deepgram response)

Streaming Response (Undocumented)

Sending Accept: application/stream+json returns newline-delimited JSON chunks as segments are transcribed. Each line:

{"text": "segment text", "start": 0.0, "end": 3.42}

This is used internally but not in the public OAS spec.

Pricing

Source: https://developers.telnyx.com/docs/voice/stt/rest-api/pricing.md

Pricing for REST API STT varies by engine and model. Contact sales or check the pricing page for current rates.

In-Call

In-Call Transcription

Source: https://developers.telnyx.com/docs/voice/stt/in-call-transcription.md

In-call transcription enables real-time STT on live voice calls. The audio codec is managed by the Telnyx platform — no format configuration needed. Two integration paths:

Voice API — transcription_start / transcription_stop commands on active calls. See the Voice API STT guide.
TeXML — XML-based call flow with transcription directives. See the TeXML transcription guide.

Engine selection (Telnyx, Google, Deepgram, Azure, xAI, AssemblyAI, Speechmatics, Soniox, Parakeet) is specified as a parameter on the transcription command. Same engines as WebSocket streaming.

API Reference (STT)

Audio

Transcribe speech to text: Transcribe speech to text. This endpoint is consistent with the OpenAI Transcription API and may be used with the OpenAI JS or Python SDK.

​Telnyx Voice: STT — Full Documentation

​

​Overview

​Quickstart

​Prerequisites

​Example output

​Example response

​What’s next

​Models

​Comparison

​Engine Details

​How to Choose

​Specifying the Engine and Model

​Migration

​WebSocket

​REST

​WebSocket

​REST

​REST

​WebSocket

​WebSocket

​WebSocket

​REST

​WebSocket

​Lifecycle

​Endpoint

​Connection Lifecycle

​1. Handshake

​2. Streaming

​3. Teardown

​Overview

​Example

​Audio Formats

​Browser Capture

​Telephony

​Raw PCM

​Recorded File

​Engine Compatibility

​Engines & Models

​Engines

​Flux Model

​End-of-Turn Detection

​Event Flow

​Configuration Profiles

​Language

​Auto-Detection

​Engine Support

​Supported Languages

​Common Codes

​Interim Results

​Endpointing

​Values

​Trade-offs

​Interaction With Utterance End

​Keyword Boosting

​keyterm — Nova-3 and Flux

​keywords — Nova (Legacy)

​Which To Use

​Examples

​Redaction

​Values

​Output

​Messages

​Client → Server

​Audio Data

​Control Messages

​Server → Client

​Transcription Result

​Utterance End

​Error

​Message Flow

​Errors

​Error Response Format

​Error Codes

​Examples

​Production Patterns

​Connection Recovery

​Backoff

​Partials

​Audio Buffering

Telnyx Voice: STT — Full Documentation

Overview

Quickstart

Prerequisites

Example output

Example response

What’s next

Models

Comparison

Engine Details

How to Choose

Specifying the Engine and Model

Migration

WebSocket

REST

WebSocket

REST

REST

WebSocket

WebSocket

WebSocket

REST

WebSocket

Lifecycle

Endpoint

Connection Lifecycle

1. Handshake

2. Streaming

3. Teardown

Overview

Example

Audio Formats

Browser Capture

Telephony

Raw PCM

Recorded File

Engine Compatibility

Engines & Models

Engines

Flux Model

End-of-Turn Detection

Event Flow

Configuration Profiles

Language

Auto-Detection

Engine Support

Supported Languages

Common Codes

Interim Results

Endpointing

Values

Trade-offs

Interaction With Utterance End

Keyword Boosting

`keyterm` — Nova-3 and Flux

`keywords` — Nova (Legacy)

Which To Use

Examples

Redaction

Values

Output

Messages

Client → Server

Audio Data

Control Messages

Server → Client

Transcription Result

Utterance End

Error

Message Flow

Errors

Error Response Format

Error Codes

Examples

Production Patterns

Connection Recovery

Backoff

Partials

Audio Buffering

Keepalive