Quickstart - Waterr.ai

Step 1: Get access

ORI-Realtime 1.5 is in research preview. Request access with a line about what you’re building — we enable preview access on your API key, usually within a day.

Step 2: Create an API key

Go to waterr.ai/settings?tab=api-keys.

Create a key

Keys look like wai_live_.... Copy it immediately — it’s shown once.

Confirm preview access

Once we’ve enabled ORI-Realtime for your key, you’re ready to connect. Keys without preview access receive a preview_access_required error on connect.

Step 3: Connect

The endpoint is a WebSocket:

wss://api.waterr.ai/v1/realtime?model=ori-realtime-1.5

Authenticate with Authorization: Bearer wai_<your_key> — or ?token=wai_<your_key> in the URL where you can’t set headers (browsers). The flow is three moves: send one session.update to configure voice and instructions, stream microphone (or file) audio as base64 Opus in input_audio_buffer.append events, and play the base64 Opus that arrives in response.audio.delta events. The model decides when to speak — there is no “send” button to press.

Python
Node.js
Browser

Uses sphn (Kyutai’s streaming Opus codec) — pip install websockets sphn numpy. Prepare a short 24 kHz mono WAV of you speaking: ffmpeg -i hello.wav -ar 24000 -ac 1 hello_24k.wav.

import asyncio, base64, json
import numpy as np
import sphn
from websockets.asyncio.client import connect

URL = "wss://api.waterr.ai/v1/realtime?model=ori-realtime-1.5"
KEY = "wai_live_..."  # your API key

async def main():
    pcm, _ = sphn.read("hello_24k.wav", sample_rate=24000)
    pcm = pcm[0]  # mono channel, float32 in [-1, 1]

    async with connect(
        URL,
        subprotocols=["realtime"],
        additional_headers={"Authorization": f"Bearer {KEY}"},
    ) as ws:
        # 1. Configure the session
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "voice": "anna",
                "instructions": {
                    "type": "constant",
                    "text": "You are a friendly, concise assistant.",
                    "language": "en",
                },
            },
        }))

        # 2. Stream the audio in 80 ms chunks, as a mic would
        async def send_audio():
            writer = sphn.OpusStreamWriter(24000)
            chunk = 1920  # 80 ms at 24 kHz
            for i in range(0, len(pcm), chunk):
                data = writer.append_pcm(pcm[i : i + chunk])
                if data:
                    await ws.send(json.dumps({
                        "type": "input_audio_buffer.append",
                        "audio": base64.b64encode(data).decode(),
                    }))
                await asyncio.sleep(0.08)
            # keep the mic "open" with silence so the turn engine
            # can detect that you finished speaking
            silence = np.zeros(chunk, dtype=np.float32)
            while True:
                data = writer.append_pcm(silence)
                if data:
                    await ws.send(json.dumps({
                        "type": "input_audio_buffer.append",
                        "audio": base64.b64encode(data).decode(),
                    }))
                await asyncio.sleep(0.08)

        sender = asyncio.create_task(send_audio())

        # 3. Receive the reply
        reader = sphn.OpusStreamReader(24000)
        reply = []
        async for message in ws:
            event = json.loads(message)
            if event["type"] == "response.text.delta":
                print(event["delta"], end="", flush=True)
            elif event["type"] == "response.audio.delta":
                chunk = reader.append_bytes(base64.b64decode(event["delta"]))
                if chunk is not None and chunk.size:
                    reply.append(chunk)
            elif event["type"] == "response.audio.done" and reply:
                break  # first reply finished — a real app keeps listening
        sender.cancel()

        sphn.write_wav("reply.wav", np.concatenate(reply), 24000)
        print("\nSaved reply.wav")

asyncio.run(main())

npm install ws. Opus encode/decode options for Node are covered in audio; this skeleton shows the session flow.

import WebSocket from "ws";

const ws = new WebSocket(
  "wss://api.waterr.ai/v1/realtime?model=ori-realtime-1.5",
  ["realtime"],
  { headers: { Authorization: `Bearer ${process.env.WATERR_API_KEY}` } }
);

ws.on("open", () => {
  ws.send(JSON.stringify({
    type: "session.update",
    session: {
      voice: "paul",
      instructions: {
        type: "constant",
        text: "You are a friendly, concise assistant.",
        language: "en",
      },
    },
  }));
  // then stream base64 Opus chunks:
  // ws.send(JSON.stringify({ type: "input_audio_buffer.append", audio: b64Opus }))
});

ws.on("message", (data) => {
  const event = JSON.parse(data.toString());
  switch (event.type) {
    case "response.text.delta":
      process.stdout.write(event.delta); // model speech, as text
      break;
    case "conversation.item.input_audio_transcription.delta":
      // live transcript of the user
      break;
    case "response.audio.delta":
      // base64 Opus — decode and play (see the Audio page)
      break;
    case "error":
      console.error(event.error.code, event.error.message);
      break;
  }
});

Browsers can’t set WebSocket headers — pass the key as ?token=. Use an ephemeral or restricted key; never ship a long-lived key in client code.

const ws = new WebSocket(
  `wss://api.waterr.ai/v1/realtime?model=ori-realtime-1.5&token=${key}`,
  ["realtime"]
);

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "session.update",
    session: {
      voice: "eve",
      instructions: { type: "constant", text: "Be brief.", language: "en" },
    },
  }));
  // capture mic → encode Opus (24 kHz mono) with WebCodecs AudioEncoder
  // or opus-recorder → send as input_audio_buffer.append (see Audio page)
};

ws.onmessage = ({ data }) => {
  const event = JSON.parse(data);
  if (event.type === "response.audio.delta") {
    // decode base64 Opus with WebCodecs AudioDecoder → play via Web Audio
  }
};

Coming from the OpenAI Realtime API? The event shapes will feel familiar — the two differences that matter: audio is Opus at 24 kHz (not PCM16), and there is no response.cancel — interruption is handled server-side when your user starts speaking. Details in the WebSocket reference.

Next steps

WebSocket reference

Every event, error code, and limit.

Audio format

Opus encode/decode in Python, Node, and the browser.

Voices

The 9 preset voices and how to pick one.

Model card

Architecture, capabilities, and limitations.

​Step 1: Get access

​Step 2: Create an API key

​Step 3: Connect

​Next steps

WebSocket reference

Audio format

Voices

Model card

Step 1: Get access

Step 2: Create an API key

Step 3: Connect

Next steps