Skip to main content
WSS
Beta. The Speech to Speech WebSocket is generally available for testing but session events, configuration, and audio formats may change in backwards-incompatible ways before GA.
Bidirectional WebSocket endpoint for real-time speech translation. This endpoint is served by realtime-api-server at wss://realtime.camb.ai/v1/realtime, separate from the /apis/live-tts/ws and /streaming-transcription/listen WebSocket endpoints.
Sessions run in one of two modes, selected with the mode query parameter or the mode field of the first session.update. fast (the default) accepts audio almost immediately and translates with the lowest latency, but supports fewer languages. slow supports the full language list and translates more accurately, at the cost of a 30s+ cold boot before the session is ready. mode replaced a model parameter that took engine codenames. Both are still accepted β€” iris resolves to fast, and lilac/violet/orchid to slow β€” so existing integrations keep working while you migrate. Authenticate with the x-api-key WebSocket request header. If your client cannot set WebSocket headers, send credentials in the first session.update event instead.

Quickstart

Use the SDK (Python or TypeScript) β€” it handles the session lifecycle (including the session.starting cold-boot wait), surfaces the server’s binary audio frames as typed audio events, and exposes typed events. Input and output audio are PCM16, mono, 24 kHz. The example below streams a WAV file and writes the translated speech to another WAV.
See the Realtime Speech Translation tutorial for the microphone quickstart, the full event list, and configuration. The sections below document the underlying wire protocol for reference (for example, if you are building a client in a language without an SDK).

Integration in 4 steps

1

Open the realtime socket

Connect to wss://realtime.camb.ai/v1/realtime. This endpoint is not under the client.camb.ai/apis namespace used by the other WebSocket API references.
2

Send `session.update` as the first message

The first WebSocket message must be a JSON session.update event. The server waits up to 10 seconds for it.
The server responds with session.created, then session.updated.
3

Stream input audio

Send microphone audio as base64-encoded bytes in input_audio_buffer.append. Only text WebSocket messages are parsed as realtime events.
Each decoded audio payload can be up to 256 KiB.
4

Read translated output

Listen for transcript, translated text, and translated audio events. response.text.delta values are additive for the current response, and response.audio.delta contains base64-encoded synthesized audio bytes.

Authentication

Prefer the WebSocket request header:
The initial session.update event can also carry credentials:
If both the request header and auth object are present, the request header credential is used.

Reference

The AsyncAPI spec above documents every client and server event. Quick lookup:

Session configuration

Voice selection

By default, translated speech is synthesized with a built-in voice for the target language. To synthesize the translation with one of your own cloned voices, include a voice object in the session configuration:
The voice must belong to your account β€” stock/built-in voice IDs are rejected with an error event. Omitting voice (or sending { "type": "default" }) uses the built-in voice. The resolved selection is echoed back in session.created. If you use the SDK, pass voice_id (Python) or voiceId (TypeScript) to realtime.connect() and it builds this voice object for you:
For the most natural-sounding results, choose a voice whose reference language matches your target_language. A large mismatch between the voice’s native language and the translation language can reduce clarity and accent accuracy.

Supported languages

source_language and target_language accept the BCP-47 tags below (case-insensitive). Pick any supported language as the source and any supported language as the target.

Client events

Server events

Limits

Billing

Active sessions are charged in billing windows and finalized on close, failure, or billing stop. If billing stops a session, the server sends an error event whose error.message is the billing close reason, then ends the realtime loop.
session.starting
type:object
type
type:string
required

session.starting

Session Created
type:object

Sent after authorization, startup, and activation complete.

type
type:string
required

session.created

session
type:object
required
mode
type:enum

Latency/quality tradeoff. fast accepts audio almost immediately and translates with the lowest latency, but supports fewer languages. slow supports the full language list and translates more accurately, at the cost of a 30s+ cold boot before the session is ready. May also be supplied as a mode query parameter on the upgrade URL; a value here takes precedence.

Available options: fast, slow
model
type:enum
deprecated

Deprecated alias for mode, kept so pre-rename integrations keep working. The retired engine codenames resolve to a mode: iris to fast, and lilac/violet/orchid to slow. mode takes precedence if both are sent. Also accepted as a model query parameter on the upgrade URL.

Available options: fast, slow, iris, lilac, violet, orchid
source_language
type:string
required

Source language tag, for example en-US.

target_language
type:string
required

Target language tag, for example de-DE.

output_modalities
type:array
item
type:enum
Available options: text, audio
voice
type:object

Output voice selection. Use the built-in voice or one of your cloned voices.

id
type:string
required

Durable realtime session ID.

Session Updated
type:object

Sent immediately after session.created with the active session configuration.

type
type:string
required

session.updated

session
type:object
required
mode
type:enum

Latency/quality tradeoff. fast accepts audio almost immediately and translates with the lowest latency, but supports fewer languages. slow supports the full language list and translates more accurately, at the cost of a 30s+ cold boot before the session is ready. May also be supplied as a mode query parameter on the upgrade URL; a value here takes precedence.

Available options: fast, slow
model
type:enum
deprecated

Deprecated alias for mode, kept so pre-rename integrations keep working. The retired engine codenames resolve to a mode: iris to fast, and lilac/violet/orchid to slow. mode takes precedence if both are sent. Also accepted as a model query parameter on the upgrade URL.

Available options: fast, slow, iris, lilac, violet, orchid
source_language
type:string
required

Source language tag, for example en-US.

target_language
type:string
required

Target language tag, for example de-DE.

output_modalities
type:array
item
type:enum
Available options: text, audio
voice
type:object

Output voice selection. Use the built-in voice or one of your cloned voices.

conversation.item.input_audio_transcription.delta
type:object
type
type:string
required

conversation.item.input_audio_transcription.delta

delta
type:string
required

Newly transcribed source-language text. Additive within one utterance; resets after the matching conversation.item.input_audio_transcription.completed.

Input Audio Transcription Completed
type:object

Completed user transcript produced by the realtime pipeline.

type
type:string
required

conversation.item.input_audio_transcription.completed

transcript
type:string
required
Response Text Delta
type:object

Incremental translated text. The delta is additive for the current response.

type
type:string
required

response.text.delta

delta
type:string
required

Additive translated text delta for the current response.

Response Text Done
type:object

Final translated text for the current response.

type
type:string
required

response.text.done

text
type:string
required

Final translated text.

Response Audio Delta
type:string

Base64-encoded synthesized output audio bytes.

Response Audio Done
type:object

Current assistant audio response is complete.

type
type:string
required

response.audio.done

Error
type:object

Structured error for unsupported recognized events and billing stop decisions.

type
type:string
required

error

error
type:object
required
message
type:string
required
Update Session
type:object

First client event. Authorizes and activates the realtime session.

type
type:string
required

session.update

session
type:object
required
mode
type:enum

Latency/quality tradeoff. fast accepts audio almost immediately and translates with the lowest latency, but supports fewer languages. slow supports the full language list and translates more accurately, at the cost of a 30s+ cold boot before the session is ready. May also be supplied as a mode query parameter on the upgrade URL; a value here takes precedence.

Available options: fast, slow
model
type:enum
deprecated

Deprecated alias for mode, kept so pre-rename integrations keep working. The retired engine codenames resolve to a mode: iris to fast, and lilac/violet/orchid to slow. mode takes precedence if both are sent. Also accepted as a model query parameter on the upgrade URL.

Available options: fast, slow, iris, lilac, violet, orchid
source_language
type:string
required

Source language tag, for example en-US.

target_language
type:string
required

Target language tag, for example de-DE.

output_modalities
type:array
item
type:enum
Available options: text, audio
voice
type:object

Output voice selection. Use the built-in voice or one of your cloned voices.

auth
type:object
api_key
type:string
required
Append Input Audio
type:object

Append base64-encoded microphone audio bytes to the realtime input stream.

type
type:string
required

input_audio_buffer.append

audio
type:string
required

Base64-encoded audio bytes. The decoded payload can be up to 256 KiB.

Clear Input Audio Buffer
type:object

Recognized but not supported in this version. The server responds with an error event.

type
type:string
required

input_audio_buffer.clear

Commit Input Audio Buffer
type:object

Recognized but not supported in this version. The server responds with an error event.

type
type:string
required

input_audio_buffer.commit

Cancel Response
type:object

Recognized but not supported in this version. The server responds with an error event.

type
type:string
required

response.cancel

Last modified on August 27, 2026