Speech-to-Speech (STS)

Conversational speech-to-speech — the caller speaks, the agent replies with voice in real time. This is the same stack as Live talk and the dashboard Live talk studio.

STS is delivered over a WebSocket, not the REST /v1/audio/* endpoints used for TTS and STT.

Endpoints

Everything terminates on the platform: your clients only ever talk to platform.oogam.in. Each WebSocket connection is its own isolated realtime session — audio and events are never mixed across connections.

Authentication

STS uses the same platform API key (sk-setu-…) as REST TTS/STT — with the naad product enabled and credit in the project wallet. Pass it as a Bearer header:

Authorization: Bearer sk-setu-…

Browser WebSockets cannot set headers, so browser clients may pass the key as a query param instead:

wss://platform.oogam.in/v1/realtime?api_key=sk-setu-…

Connections are metered per actual connection second and billed to the key's project wallet at the naad-sts-v1 per-minute rate — same as Live talk in the dashboard.

Audio formats

JSON control events share the same WebSocket.

Important differences from REST TTS/STT

• Language codes are 2-letter (hi, en, mr) — not HIN / ENG.
• Voice ids are f1, m1, … — not aditi / arjun. List them via GET /api/naad/sts/voices.

Call flow

1. GET /api/naad/sts/v1/realtime/session — confirm protocol
2. Open the WebSocket
3. Send set_lang then set_voice
4. Wait for voice_ack
5. Send start_utterance
6. Stream mic PCM continuously as binary frames
7. Handle state, stt, reply, and binary agent audio
8. On hang-up: stop_utterance / close the socket

Client → server events

{"type":"set_lang","value":"hi"}
{"type":"set_voice","voice":"f1"}
{"type":"set_context","system":"You are a helpful support agent…","kb_id":"kb_1","temperature":0.3}
{"type":"start_utterance"}
{"type":"stop_utterance"}
{"type":"reset"}

Server → client events

Inspect the protocol

curl -sS "https://platform.oogam.in/api/naad/sts/v1/realtime/session"
curl -sS "https://platform.oogam.in/api/naad/sts/voices"
curl -sS "https://platform.oogam.in/api/naad/sts/languages"

Node example

import WebSocket from "ws";

const ws = new WebSocket("wss://platform.oogam.in/v1/realtime", {
  headers: { Authorization: `Bearer ${process.env.SETU_API_KEY}` },
});

ws.on("open", () => {
  ws.send(JSON.stringify({ type: "set_lang", value: "hi" }));
  ws.send(JSON.stringify({ type: "set_voice", voice: "f1" }));
});

ws.on("message", (data, isBinary) => {
  if (isBinary) {
    // PCM16 LE mono @ 24 kHz — play to speaker
    return;
  }
  const msg = JSON.parse(data.toString());
  if (msg.type === "voice_ack") {
    ws.send(JSON.stringify({ type: "start_utterance" }));
    // then stream mic as binary PCM16 LE mono @ 16 kHz
  }
  if (msg.type === "stt") {
    console.log("user:", msg.text ?? msg.value, msg.replace ? "(replace)" : "");
  }
  if (msg.type === "reply") {
    console.log("agent:", msg.text ?? msg.value);
  }
});

Builtin voices

Offline re-voice (not conversational STS)

To re-voice a recorded file without a live call, use the REST voice changer instead:

curl https://platform.oogam.in/v1/audio/voice-changer \
  -H "Authorization: Bearer $SETU_API_KEY" \
  -F model="naad-s2s-v1" \
  -F voice="arjun" \
  -F file="@speech.wav" \
  --output changed.wav

See also Audio & Voice for TTS and STT.