VoiceRun STT Router

VoiceRun STT Router is one realtime WebSocket interface for VoiceRun STT Model and external speech-to-text models. Select a primary model and optional ordered fallback models; audio input and transcription events stay the same.

wss://api.voicerun.com/v1/stt

How It Works#

1. Connect — open the WebSocket with your VoiceRun API key.
2. Configure — send session.update with a primary model and optional fallback_models.
3. Stream — send base64 audio in input_audio_buffer.append messages.
4. Receive — replace the current hypothesis on transcription.delta; consume the completed turn from turn.ended.
5. Close — either close the WebSocket directly, or send session.close for a graceful shutdown and wait for session.closed. The protocol message is optional.

The gateway normalizes provider protocols. Provider-specific messages never escape the socket.

session.close does not commit or flush unfinished audio. Wait for the final turn.ended before closing a live session. When streaming a finite recording, append trailing silence so provider endpointing can finish the last turn; see Messages and Examples.

Authentication and billing#

One VoiceRun API key works for every enabled model:

1. Sign in and open your VoiceRun profile.
2. Under Personal Access Tokens, click Add PAT and copy the generated token.
3. Use that PAT as VOICERUN_API_KEY; keep it server-side and out of source control.

ws = await websockets.connect(
    "wss://api.voicerun.com/v1/stt",
    additional_headers={"Authorization": "Bearer YOUR_VOICERUN_API_KEY"},
)

Browser clients that cannot set an Authorization header may use ?token=YOUR_VOICERUN_API_KEY. Avoid putting keys in URLs outside browser-only integrations.

{
  "type": "session.update",
  "model": "voicerun-asr-realtime-v1",
  "fallback_models": ["nova-3", "gpt-4o-transcribe"],
  "language": "en"
}

Usage is charged to your VoiceRun credit balance at the published rate for the selected model. VoiceRun STT Model is free during its preview; external models continue to use their published rates. VoiceRun manages provider credentials, and provider credential fields are rejected by the public API.

Automatic model fallback#

fallback_models is an ordered list of up to five model names. If the active provider fails at runtime, the Router settles that model's accepted audio, starts the next available model at its published rate, and emits session.model_changed.

The Router retains up to eight seconds of input audio and replays it into the fallback model so an in-progress turn can continue. Replayed audio is charged to the fallback model because that model processes it. Each configured model is attempted at most once.

Fallback models inherit the session's shared configuration. If the new model does not support a setting used by the primary model, its adapter ignores that setting; the incompatibility does not prevent failover. Choose models with compatible behavior when a particular setting is essential to the conversation.

Fallback is not attempted for invalid configuration, an invalid VoiceRun API key, insufficient credits, or a concurrency limit. The fallback chain cannot be changed after the session becomes active.

Supported Models#

Undated aliases may resolve to a tested provider snapshot while retaining the same public model selector.

This list covers the standalone STT Router only. VoiceRun voice agents select STT models from a separate catalog — see Speech to Text for the models available under Deployment.spec.stt.

Audio Format#

Input defaults to raw PCM16 little-endian, mono, at 16 kHz. Set input_audio_format to pcm16 or mulaw and sample_rate to a value from 8,000 through 48,000 Hz; VoiceRun converts it to the rate required by the selected engine.

Chunks around 20–100 ms work well for live audio. For a finite recording, append trailing silence so provider-side endpointing can close the final turn.

Unified Events#

All models use the VoiceRun STT v1 vocabulary:

audio.append remains accepted as an input alias. Output always uses the v1 event names above.

VoiceRun STT Model additionally supports dynamic per-turn context, language constraints, and semantic server-side turn-taking. See VoiceRun STT Model.