Realtime API

PreviousNext

The Realtime WebSocket path of Lanson Live API.

What it does

Stream live speech with Lanson Live API. Open a WebSocket, send PCM16LE audio frames, and receive completed transcript events. No model parameter is required; language and optional features are configured through session.update.

Endpoint

WSS /v1/audio/transcriptions/stream

Authentication

Three authentication methods:

MethodUsageUse case
Bearer headerAuthorization: Bearer sk-...Server-side clients
Query token?access_token=rt_...Browser (session token)
Query token (alias)?token=rt_...Browser (session token)

Session tokens are obtained via POST /v1/audio/transcriptions/session-token and are valid for 60 seconds. See Authentication.

Connection

Upgrade conditions

  • Request must be a WebSocket upgrade, otherwise 426 websocket_required
  • Gateway must be enabled, otherwise 503 gateway_disabled
  • Connection quota must pass (concurrent connections + handshake rate)

On success

Receives a session.created event:

{
  "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": false },
  "limits": {
    "max_concurrent_utterances": 8,
    "max_session_seconds": 28800,
    "idle_timeout_seconds": 180,
    "remaining_audio_seconds": 720000
  }
}

Limits depend on the plan; see Rate Limits.

Message format

All client audio is sent as JSON text frames. Binary PCM frames are not transcribed by the public gateway today.

  • Text frames: JSON objects, must contain a type field
  • Audio: base64 PCM16LE in input_audio_buffer.append (binary frames are not transcribed today)

WebSocket close codes

CodeClose reasonMeaning
1000—Normal close
1008session_audio_limitRealtime session audio budget exceeded
1008audio_quota_exhaustedBilling-window audio budget exhausted
1008session_duration_limitSession wall-clock duration exceeded
1009frame_too_largeAudio frame exceeds 1 MiB
1011client_errorClient socket error or unexpected gateway error
4408idle_timeoutNo audio received within idle timeout window