Client Messages

PreviousNext

Client messages for the Lanson Live API Realtime connection.

Messages the client sends over the WebSocket connection.

Overview

typeTransportPurpose
input_audio_buffer.appendText frame (JSON)Send base64-encoded PCM audio (supported)
input_audio_buffer.flushText frame (JSON)Accepted compatibility message; no guaranteed segment finalization
flushText frame (JSON)Accepted alias; same limitation
session.updateText frame (JSON)Set language, refinement, target_languages, or translate_to

input_audio_buffer.append

Send base64-encoded PCM16LE audio data.

{
  "type": "input_audio_buffer.append",
  "audio": "<PCM16LE base64>"
}
FieldTypeRequiredDescription
typestringyesMust be "input_audio_buffer.append"
audiostringyesBase64-encoded PCM16LE audio data

Errors:

  • invalid_audio: audio is empty or not valid base64

Binary audio frames — not supported today

input_audio_buffer.flush

The message is accepted for compatibility, but the current public Realtime session handler does not implement a manual-flush action. Do not rely on it to end an utterance, deliver pending results, or produce a full-session final transcript.

{ "type": "input_audio_buffer.flush" }

"flush" is an accepted alias with the same limitation. Continue streaming audio, including natural silence, for server-side segmentation. Keep the socket open while expected utterance results are in flight.

session.update

Optionally set the audio language before sending audio. Can also be sent at any time after connection to switch language.

{
  "type": "session.update",
  "language": "zh"
}

Supported fields

FieldTypeDescription
languagestring | nullAudio language. A concrete code (e.g. zh, en) is recommended for accuracy; "auto", null, or omitting it enables detection.
refinementboolean | stringOpt in to per-utterance AI refinement before delivery. true selects the default lite profile; "lite" / "pro" select a profile explicitly; false disables it. Off by default and fixed before audio. Lite is included in the base transcription price; Pro is billed as the realtime refinement add-on. Requires gateway availability.
target_languagesstringTranslation targets (BCP-47, max 8). Fixed for the session; send before audio.
translate_tostringSingle-language shorthand for target_languages. Fixed for the session.

language can change at any time. target_languages / translate_to are session-fixed: the first accepted value wins, and later changes return session_features_locked.

The gateway confirms the applied state with a session.updated event.

Switching language mid-session

  • A concrete code always wins: the session uses it immediately and does not run detection.
  • Sending "auto" (or null) resets detection state and re-triggers detection on subsequent speech. Use this when the language changes or becomes unknown.
  • Sending "auto" again while already in auto mode also resets and re-detects.
  • Transcripts already delivered keep their language; the new setting applies to speech transcribed after the update.

Errors

  • bad_json: JSON parse failure
  • bad_message: Not a JSON object or unsupported type
  • invalid_audio: Invalid audio data
  • invalid_target_languages: No valid BCP-47 tag in target_languages
  • translation_unavailable: Translation is not configured on this gateway
  • refinement_unavailable: Correction is not configured on this gateway
  • session_features_locked: Tried to change translation targets after the session feature set was frozen