Message Reference

The VoiceRun STT v1 protocol is shared by every model at wss://api.voicerun.com/v1/stt.

Client Messages#

`session.update`#

Send this after session.created. Fields may be flat or nested under session; flat fields win when both are supplied. provider is not required because the gateway resolves it from model.

Field	Type	Required	Description
`model`	string	Yes	STT model selector
`fallback_models`	string[]	No	Ordered fallback model selectors; up to five, distinct from the primary model
`language`	string	No	Language code, or `auto` when supported
`context`	string	No	Context or keyword biasing; support varies by model
`input_audio_format`	string	No	`pcm16` (default) or `mulaw`
`sample_rate`	integer	No	Input sample rate, 8000–48000; default 16000
`turn_detection`	string	No	`server` or `provider`; support varies by model
`eou_threshold`	number or object	No	Advanced end-of-turn threshold for VoiceRun STT Model and Deepgram Flux
`eot_timeout_ms`	integer	No	Advanced end-of-turn timeout for VoiceRun STT Model and Deepgram Flux
`vad_stop_ms`	integer	No	VoiceRun STT Model silence before end-of-turn scoring
`allowed_languages`	string	No	VoiceRun STT Model language allow-list

{
  "type": "session.update",
  "session": {
    "model": "voicerun-asr-realtime-v1",
    "fallback_models": ["nova-3", "gpt-4o-transcribe"],
    "language": "en",
    "context": "insurance, policy, premium",
    "input_audio_format": "pcm16",
    "sample_rate": 16000
  }
}

Provider credential fields are not part of the public protocol and are rejected. Unsupported model settings produce a separate warning event and are not silently applied.

Every fallback model is validated before admission. model and fallback_models cannot change after the session becomes active; dynamic model-specific settings such as context may still be updated when the active model supports them.

Fallback models inherit the shared session settings. Unsupported settings are ignored by the newly active model and do not cause the fallback attempt to fail.

`input_audio_buffer.append`#

Append a base64-encoded audio chunk. audio.append is accepted as an alias.

{"type":"input_audio_buffer.append","audio":"AAAA//8AAAEAAAD/////AAAB..."}

`session.close`#

Gracefully finish the socket. Closing the WebSocket directly is also supported.

{"type":"session.close"}

Server Messages#

`session.created`#

{"type":"session.created","session":{"id":"c4b2d518-4bad-4ba5-b66a-006cbed8c233"}}

`session.updated`#

Confirms the applied, secret-free configuration.

{
  "type": "session.updated",
  "model": "nova-3",
  "language": "en",
  "sample_rate": 16000,
  "input_audio_format": "pcm16"
}

`warning`#

Reports settings that the selected model cannot honor. The session remains active.

{
  "type": "warning",
  "code": "unsupported_for_model",
  "message": "some session fields are not supported by this model",
  "fields": ["eou_threshold"]
}

`session.model_changed`#

The active provider failed and the Router successfully moved the live session to the next configured model. replayed_audio_ms is the amount of buffered input replayed into the new model, up to eight seconds.

{
  "type": "session.model_changed",
  "from_model": "voicerun-asr-realtime-v1",
  "to_model": "nova-3",
  "reason": "provider_unavailable",
  "replayed_audio_ms": 2400
}

Transcription events after this message belong to to_model. The Router discards queued hypotheses from the failed model before switching.

`transcription.delta`#

The current full hypothesis. Replace the previous hypothesis rather than concatenating deltas.

{"type":"transcription.delta","text":"hello how are","language":"en"}

`turn.ended`#

Final transcript for a completed turn. External engines use reason: "provider" when their own endpointing closed it.

{
  "type": "turn.ended",
  "text": "hello how are you doing today",
  "language": "en",
  "reason": "provider"
}

`error`#

{"type":"error","code":"insufficient_credits","message":"insufficient VoiceRun credits"}

Common codes include invalid_request, unsupported_model, unsupported_for_model, unauthorized, insufficient_credits, auth_unavailable, service_unavailable, provider_error, concurrency_limit, session_not_configured, and session_timeout. invalid_provider_credentials indicates a VoiceRun-managed provider integration problem; customers never send provider credentials through this API.