Server Events

PreviousNext

Lanson Live API WebSocket events, StableStream™ output, and correction metadata.

Events Lanson Live API pushes over WS /v1/audio/transcriptions/stream. Event identifiers remain unchanged by product or technology branding.

StableStream™ and LiveFinal™ on this endpoint

StableStream™ describes stable, readable live text. LiveFinal™ describes progressive correction and segment finalization. On this public endpoint, optional refinement runs before a single conversation.item.input_audio_transcription.completed event is delivered for each successfully processed utterance.

  • text is the delivered segment; raw_text is recognition output before optional correction.
  • transcript.state is stable; transcript.revision is currently always 0.
  • transcript.correction_applied indicates that correction changed the text. Refinement requires opt-in and gateway availability.
  • There are no partial/revision events, separate live.correction.completed events, or session-wide final transcript events on this endpoint.

Technology names are not wire types. See LiveFinal™ for the processing boundaries and Transcript Lifecycle for client behavior.

Overview

typeSourceDescription
session.createdGatewaySent on connection establishment
session.updatedGatewayConfirms an applied session.update
input_audio_buffer.speech_startedUpstreamSpeech segment detected
input_audio_buffer.speech_stoppedUpstreamSpeech segment ended
conversation.item.input_audio_transcription.completedUpstreamA speech segment has been transcribed (primary output)
live.translation.completedGatewayTranslation for one utterance + target language
lanson.throttledGatewayThrottle notification (max once per second)
errorGateway / upstreamError event

session.created

Sent by the gateway immediately after connection.

{
  "type": "session.created",
  "request_id": "...",
  "session_id": "sess_...",
  "audio": { "format": "pcm_s16le", "sample_rate": 16000, "channels": 1 },
  "turn_detection": { "type": "server_vad" },
  "plan": "pro",
  "features": {
    "asr_correction": true,
    "refinement": false,
    "translation": true,
    "target_languages": []
  },
  "limits": {
    "max_concurrent_utterances": 8,
    "max_session_seconds": 28800,
    "idle_timeout_seconds": 180,
    "remaining_audio_seconds": 720000
  }
}

Limits are plan-dependent — the example above shows a pro session. See Rate Limits for all plans.

FieldTypeDescription
session_idstringSession identifier
audio.formatstringFixed: pcm_s16le
audio.sample_ratenumberFixed: 16000
audio.channelsnumberFixed: 1
turn_detection.typestringFixed: server_vad
planstringCurrent plan
features.asr_correctionbooleanWhether realtime ASR correction is available on this gateway (opt-in per session)
features.refinementboolean | stringfalse when off, or the enabled profile id ("lite" / "pro")
features.translationbooleanWhether translation is configured on this gateway
features.target_languagesstringFrozen translation targets (empty until session.update)
limits.max_concurrent_utterancesnumberMax concurrent utterances
limits.max_session_secondsnumberMax session duration (seconds)
limits.idle_timeout_secondsnumberIdle timeout (seconds)
limits.remaining_audio_secondsnumber | nullRemaining audio budget (null when unlimited)

session.updated

Confirms the state applied by a session.update. Sent for every accepted update, including language-only updates.

{
  "type": "session.updated",
  "request_id": "...",
  "session_id": "sess_...",
  "language": "zh",
  "language_source": "client",
  "target_languages": ["en", "ja"],
  "features": {
    "asr_correction": true,
    "refinement": false,
    "translation": true
  }
}
FieldTypeDescription
languagestring | nullEffective source language (null while auto-detection is undecided)
language_sourcestringclient or auto
target_languagesstringFrozen translation targets
features.asr_correctionbooleanWhether realtime ASR correction is available on this gateway
features.refinementboolean | stringfalse when off, or the enabled profile id ("lite" / "pro")
features.translationbooleantrue when target_languages is non-empty

input_audio_buffer.speech_started

VAD detected the start of a speech segment.

{
  "type": "input_audio_buffer.speech_started",
  "request_id": "...",
  "utterance_index": 0
}

input_audio_buffer.speech_stopped

VAD detected the end of a speech segment.

{
  "type": "input_audio_buffer.speech_stopped",
  "request_id": "...",
  "utterance_index": 0,
  "reason": "end_of_speech",
  "audio_duration_ms": 3200,
  "speech_duration_ms": 2800
}
FieldTypeDescription
utterance_indexnumberSpeech segment number
reasonstringStop reason
audio_duration_msnumberTotal audio duration
speech_duration_msnumber?Actual speech duration
split_offset_msnumber?Split offset
split_rmsnumber?Split RMS value

conversation.item.input_audio_transcription.completed

Primary output event. A speech segment has been transcribed.

{
  "type": "conversation.item.input_audio_transcription.completed",
  "request_id": "...",
  "session_id": "sess_...",
  "utterance_index": 0,
  "text": "The weather is nice today",
  "raw_text": "The weather is nice today",
  "language": "en",
  "language_source": "auto",
  "language_provisional": false,
  "audio_duration_ms": 3200,
  "latency_ms": 124,
  "stt_endpoint": "https://.../v1/audio/transcriptions",
  "worker_id": "cohere-s1",
  "transcript": {
    "id": "tr_0",
    "context_id": "ctx_sess_...",
    "state": "stable",
    "revision": 0,
    "safe_for_downstream": true,
    "correction_applied": false,
    "language_source": "auto",
    "language_provisional": false
  }
}
FieldTypeDescription
utterance_indexnumberSpeech segment number
textstringFinal transcribed text
raw_textstringText before optional correction
languagestringLanguage used for the request
language_sourcestringclient (explicit session.update) or auto (session detection)
language_provisionalbooleantrue while auto-detection has not locked yet (best-effort language)
language_detection_errorstring?Present when auto-detection failed for this utterance
audio_duration_msnumberAudio duration
latency_msnumberProcessing latency
stt_endpointstringUpstream STT endpoint that produced the result
worker_idstringUpstream worker that produced the result
transcript.idstringTranscript record id
transcript.context_idstringSession-scoped context id
transcript.statestringstable for the primary output
transcript.revisionnumberCurrently 0; this endpoint does not emit later revisions
transcript.safe_for_downstreambooleanBasic readiness signal (false for empty text or a detection error); not an accuracy guarantee
transcript.correction_appliedbooleanWhether ASR correction changed the text
transcript.language_sourcestringSame as the top-level language_source
transcript.language_provisionalbooleanSame as the top-level language_provisional
transcript.language_detection_errorstring?Same as the top-level language_detection_error

Language fields and UI display

In auto mode, language is the language the session detected and used for this utterance. The client can display it directly:

  • language_source: "client" — the client explicitly set this language; it is not a detection result.
  • language_source: "auto" — the language came from session detection.
  • language_provisional: true — detection is still voting; show the language as provisional (for example “detecting…” or a muted badge). A later event with language_provisional: false confirms the locked language.
  • language_detection_error present — detection failed; show “unknown” and retry on the next utterance rather than displaying a wrong language.

Detection is delivered with the utterance's completed event; there is no separate client event for "language detected". If the UI needs the language before sending audio, call POST /v1/audio/language-detection first.

live.translation.completed

Translation for one utterance and one target language. One event per target language, emitted independently and never blocking the source transcript.

{
  "type": "live.translation.completed",
  "request_id": "...",
  "session_id": "sess_...",
  "utterance_index": 0,
  "language": "en",
  "text": "The weather is nice today",
  "source_text": "今天天气不错",
  "source_language": "zh",
  "latency_ms": 180
}
FieldTypeDescription
utterance_indexnumberMatches the source conversation.item.input_audio_transcription.completed event
languagestringTarget language (normalized BCP-47)
textstringTranslated text
source_textstringRaw ASR line the translation is based on
source_languagestring?Source language used for this utterance
latency_msnumberTranslation latency

lanson.throttled

Gateway throttle notification, sent at most once per second.

{
  "type": "lanson.throttled",
  "reason": "concurrent_utterance_limit",
  "dropped_audio_frames": 3,
  "in_flight_utterances": 2
}
reason valueMeaning
concurrent_utterance_limitConcurrent utterance limit exceeded
client_backpressureClient is not reading events fast enough

error

Error event. Can be sent at any time during the WebSocket connection.

{
  "type": "error",
  "code": "audio_frame_too_large",
  "message": "Audio frame exceeds maximum size.",
  "request_id": "..."
}

Error codes are listed in Errors.

Event ordering

  1. session.created — Session initialized upon WebSocket handshake.
  2. session.update — Client optionally sets language and target_languages (recommended before audio).
  3. session.updated — Gateway confirms the applied session state.
  4. input_audio_buffer.append — Client streams base64 PCM16 audio frames.
  5. input_audio_buffer.speech_started — Server-side VAD detects start of speech.
  6. input_audio_buffer.append — Client continues streaming speech audio.
  7. input_audio_buffer.speech_stopped — VAD detects silence or segment boundary.
  8. conversation.item.input_audio_transcription.completed — Stable transcription text delivered.
  9. live.translation.completed — One event per target language, as each translation finishes.
  10. (Repeats for each utterance in the stream)
  11. Session close.