Live API (Realtime)

The Live API streams audio over a WebSocket connection and returns incremental transcription (and, optionally, translation) results as the audio arrives — no need to wait for the full recording before you get text back.

Connecting

Connecting has two steps: mint a short-lived client secret from your backend, then open the WebSocket from your client using that secret.

Step 1 — Mint a client secret

POST https://api.lelapa.ai/v1/realtime/client_secrets

This call must be made server-side — it requires your real X-CLIENT-TOKEN and should never be embedded in browser or mobile client code. Your backend calls this endpoint, then hands the returned short-lived value to the client that will actually open the WebSocket.

Headers

Body

Code
{
  "value": "vv_ek_68af296e8e408191a1120ab6383263c2",
  "expires_at": 1756310470,
  "session": {
    "id": "sess_abc123",
    "type": "translation",
    "audio": {
      "input": { "format": { "type": "audio/pcm", "rate": 24000 } },
      "output": { "language": null }
    }
  }
}

Step 2 — Open the WebSocket

WSS wss://api.lelapa.ai/v1/realtime

Browsers cannot set arbitrary headers during a WebSocket handshake, so authentication is passed via the Sec-WebSocket-Protocol field instead — the same workaround OpenAI's Realtime API uses. Pass an array of subprotocols to your WebSocket client:

Code
["realtime", "vulavula-insecure-api-key.vv_ek_68af296e8e408191a1120ab6383263c2"]

If you're connecting from a trusted backend process (not a browser), you can skip the client-secret step entirely and pass your X-CLIENT-TOKEN directly the same way — but the two-step flow is required for any client-side code.

Session Configuration

Send a session.update event right after connecting (or include session in the client-secret request) to configure the session:

Code
{
  "type": "session.update",
  "session": {
    "audio": {
      "input": {
        "format": { "type": "audio/pcm", "rate": 24000 },
        "transcription": { "model": "vulavula-live", "language": "zul" }
      },
      "output": { "language": "eng" }
    }
  }
}

Supported Language Codes

Language codes are ISO 639-1 (two-letter) or ISO 639-3 (three-letter), matching OpenAI's Speech-to-Text convention — either form works.

Client Events

Code
import base64
import json

await ws.send(json.dumps({
    "type": "session.input_audio_buffer.append",
    "audio": base64.b64encode(pcm16_chunk).decode(),
}))

Server Events

Code
{
  "type": "session.input_transcript.delta",
  "event_id": "event_123",
  "delta": "Sawubona"
}

Code
{
  "type": "session.output_transcript.delta",
  "event_id": "event_124",
  "delta": "Hello"
}

Code
{
  "type": "error",
  "event_id": "event_125",
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_event",
    "message": "The 'type' field is missing.",
    "param": null
  }
}

Differences from OpenAI's Realtime API

This API is intentionally close to OpenAI's Realtime API, but it is not a byte-for-byte clone. Known gaps:

• No WebRTC transport. WebSocket only — OpenAI recommends WebRTC for browser clients; we don't currently offer that transport.
• No translated-audio output. Vulavula's translation is text-only. OpenAI's translation mode can also stream synthesized translated speech (session.output_audio.delta); this API never emits that event.
• One unified session type, not separate transcription-only and translation resources. Toggle translation on/off per session with audio.output.language, rather than connecting to a different endpoint. session.type is always reported as "translation", matching OpenAI's translation session discriminator, regardless of whether translation is enabled for that session.
• Different subprotocol prefix. vulavula-insecure-api-key. instead of openai-insecure-api-key. — same mechanism, different namespace.

Full Example

See the runnable Python and browser examples in vulavula-examples for a complete end-to-end client.