How it works
The realtime endpoint is a two-step flow:- 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 model.
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: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. Retiring 2026-10-20 (see below).gemini-3.1-flash-live-preview— the Gemini 3.x successor to the model above, at the same per-minute price. Use it for new voice-agent work.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.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, zhstring
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, Zubenelgenubistring
Response 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. 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 Transcriptions — speech-to-text, sync
- Rate Limits — concurrency model + 429 shapes