How it works
The realtime endpoint is a two-step flow because of how browser security and the upstream realtime auth model interact:- POST mints a short-lived session token (5 min TTL) and returns a
ws_url. - 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.
Flow
The client must wait for theBidiGenerateContentSetupComplete 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
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: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.
model keeps the default native-audio behavior unchanged.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, zhOne 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, ZubenelgenubiResponse shape
200 OK from POST /v1/live/sessions:
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 tokenPOST /v1/live/sessions/{id}/heartbeat— keep session alive (every 30s)POST /v1/live/sessions/{id}/end— close session and settle billingwss://api.kymaapi.com/v1/live/proxy/{id}?token=…— WebSocket bidirectional audio
See also
- Audio Understand — non-realtime audio Q&A (tone, music, scene)
- Audio Transcriptions — speech-to-text, sync
- Rate Limits — concurrency model + 429 shapes
- Models —
gemini-3-flash-audio— companion model for non-realtime audio understanding