This page describes the Lanson Live API public Realtime endpoint, WS /v1/audio/transcriptions/stream. LiveFinal™ names the correction/finalization mechanism; StableStream™ names the stable, readable output behavior. Neither name is an event type.
State flow
speech_started → speech_stopped → recognition → optional refinement → completed
→ optional translationRecognition and refinement are server processing stages. The current endpoint exposes a single completed transcript per successfully processed utterance, not partial → revision → final events.
Event semantics
speech_started
VAD detected the start of a speech segment.
- At this point: no transcribed text yet
- Client action: optionally show a "listening" indicator
- Mutable: no,
utterance_indexis fixed
speech_stopped
VAD detected the end of a speech segment (silence or a segmentation boundary).
- At this point: recognition begins; optional refinement follows before delivery
- Client action: optionally show "processing" state
- Mutable: no
conversation.item.input_audio_transcription.completed
A speech segment has been transcribed. This is the primary output.
- At this point:
textis stable and will not change - Client action: display or persist
text, ordered byutterance_index - Mutable: no, text is final
- Can trigger downstream: check
transcript.safe_for_downstreamand your application's accuracy requirements
When is text stable?
The text in a conversation.item.input_audio_transcription.completed event is final. Once received, it will never be modified for that utterance.
This is a delivery guarantee, not an accuracy guarantee. Auto-detected language may still be provisional; empty text or a language-detection error makes safe_for_downstream false.
Correction and translation
Enable refinement before audio when the gateway reports correction availability. It is off by default; the default lite profile is included in the base transcription price, and pro is billed as the realtime refinement add-on. Correction runs before completed; raw_text preserves recognition output, text is the delivered result, and transcript.correction_applied reports whether correction changed it. If correction fails, the service falls back to the raw output.
transcript.state is currently stable and transcript.revision is 0. The public endpoint does not send a separate correction event, later transcript revisions, or a session-wide final event.
When translation is enabled, live.translation.completed arrives independently for each target language. It uses raw source text and associates the result by utterance_index. A missing translation should not block rendering the source text.
utterance_index
Each speech segment has a unique, incrementing utterance_index. Use it to:
- Order transcribed results
- Detect missing events (index gaps)
- Merge into a complete transcript
Concurrent utterances
The upstream may process multiple speech segments simultaneously. limits.max_concurrent_utterances limits concurrency. When exceeded, frames are dropped and lanson.throttled is sent.
No partial text
In the current version:
- No partial transcription is pushed: no intermediate text before
transcription.completed - One result per utterance: each utterance produces one
completedevent - Text is immediately stable: no partial → final transition needed on the client
This means clients do not need a partial-text replacement protocol on this endpoint. They still need to order concurrent results, handle language uncertainty and errors, and avoid layout shifts in their UI.
Persist completed results as they arrive. Do not infer that a flush message or socket close will produce a full-session final transcript; see Client Messages.
Related
- StableStream™ — readable output behavior
- LiveFinal™ — correction and finalization
- Build a Stable Caption UI — UI implementation
- Server Events — event field reference