Skip to main content
Kyma’s realtime audio endpoint streams live conversation audio between your client and Google’s Gemini Live native-audio model. Use it for voice agents, live translation, interactive tutors, and any product where the user speaks and the model speaks back in real time.

How it works

The realtime endpoint is a two-step flow because of how browser security and the upstream realtime auth model interact:
  1. POST mints a short-lived session token (5 min TTL) and returns a ws_url.
  2. WebSocket opens to wss://api.kymaapi.com/v1/live/proxy/{id}?token=… — Kyma terminates this connection and proxies it to the upstream realtime API using server-side credentials.
Why a server-side proxy: the upstream realtime API does not yet expose an ephemeral-token endpoint, and handing a browser a long-lived upstream credential would grant broad access for an hour — unsafe. A short-lived session token plus a server-side proxy is the recommended architecture for browser clients. Same Google Gemini Live model, same voices, same languages as before — now scaling to 5000 concurrent sessions (up from a 50-session cap).

Flow

The client must wait for the BidiGenerateContentSetupComplete frame before sending audio. Frames sent before setup completes will be dropped silently.

Quickstart — browser JS

1

Mint the session

2

Open the WebSocket

3

Capture mic with AudioWorklet

MediaRecorder outputs Opus/WebM container, not raw PCM. The realtime API requires PCM16 16kHz mono. Use AudioWorklet to tap raw Float32 samples from getUserMedia, downsample 48kHz → 16kHz, and quantize to Int16. Open-source browser audio-capture examples (Apache-2.0) cover the full implementation.
Pseudo-code outline:
4

Play audio response

The model returns PCM16 24kHz audio chunks (base64-wrapped JSON). Decode to a Float32Array, schedule into an AudioBufferSourceNode:
5

Heartbeat and end

Audio format reference

Note the asymmetric sample rates. The output playback context must be 24 kHz; using 16 kHz will pitch the model’s voice up by 50%.

Configuration

The mint request body accepts:
model
string
default:"gemini-2.5-flash-native-audio-preview-12-2025"
Which Gemini Live model to run. One of:
  • gemini-2.5-flash-native-audio-preview-12-2025 (default) — conversational native-audio understanding + generation. Use for voice agents and multilingual chat.
  • gemini-3.5-live-translate-preview — low-latency speech-to-speech translation across 70+ languages, preserving the speaker’s intonation, pacing, and pitch. Use for live translation.
Omitting model keeps the default native-audio behavior unchanged.
config.speech_config.language_code
string
default:"en"
BCP-47 short code. One of:ar, bn, de, en, es, fa, fr, hi, id, it, ja, ko, nl, pl, pt, ru, sv, ta, te, th, tr, ur, vi, zh
config.speech_config.voice_config.prebuilt_voice_config.voice_name
string
default:"Kore"
One of 30 prebuilt voices:Achernar, Achird, Algenib, Algieba, Alnilam, Aoede, Autonoe, Callirrhoe, Charon, Despina, Enceladus, Erinome, Fenrir, Gacrux, Iapetus, Kore, Laomedeia, Leda, Orus, Pulcherrima, Puck, Rasalgethi, Sadachbia, Sadaltager, Schedar, Sulafat, Umbriel, Vindemiatrix, Zephyr, Zubenelgenubi
config.system_instruction
string
Currently dropped on the proxy path. If you pass a custom instruction it will be ignored and the default conversational persona is used. Threading this through the token store is a planned follow-up. Contact Kyma if you need it before then.

Response shape

200 OK from POST /v1/live/sessions:
The session_token is single-use — once consumed by your WebSocket handshake it is invalidated, so a leaked token cannot be replayed. The token TTL is 5 minutes; if you don’t open the WebSocket within that window the session is reaped and you can mint a fresh one.

Pricing

Unused minutes are refunded on session end. Kyma marks up Google’s wholesale rate by 1.35× — same markup convention as every other Kyma model. Sessions are settled minute-by-minute; if you end after 4m30s the 5th minute is refunded. The initial collateral hold (≈5 minutes) is placed on session create and released against settled minutes when the session ends.

Limits

Need higher concurrency? See Rate Limits — Need higher limits?.

Errors

POST /v1/live/sessions: WebSocket close codes:

Reference

  • POST /v1/live/sessions — mint a session token
  • POST /v1/live/sessions/{id}/heartbeat — keep session alive (every 30s)
  • POST /v1/live/sessions/{id}/end — close session and settle billing
  • wss://api.kymaapi.com/v1/live/proxy/{id}?token=… — WebSocket bidirectional audio

See also