Use this file to discover all available pages before exploring further.
This is the shortest path to a working voice loop. Pick the tab that matches where your code runs, copy the snippet, and swap in your API key.For the full protocol (events, config fields, per-provider notes, billing, transcription, tool flow), see the Realtime protocol.
Create a project-scoped runtime API key in the Opper dashboard.
2
Open a session
Server (Node.js)
Browser (ephemeral ticket)
Server-side clients connect directly with a bearer token. This is the quickest way to check that the endpoint works.
npm install ws
import WebSocket from "ws";const ws = new WebSocket("wss://api.opper.ai/v3/realtime", { headers: { Authorization: `Bearer ${process.env.OPPER_API_KEY}` },});ws.on("open", () => { ws.send(JSON.stringify({ type: "session.start", config: { model: "openai/gpt-realtime-2", voice: "marin", instructions: "You are a concise voice assistant.", }, }));});ws.on("message", (raw) => { const ev = JSON.parse(raw.toString()); if (ev.type === "session.started") { console.log(`live: ${ev.session_id} @ ${ev.output_sample_rate}Hz`); } if (ev.type === "audio.delta") { // ev.audio is base64-encoded PCM16. Pipe to your audio player. }});
Browsers can’t set an Authorization header on the native WebSocket constructor. Mint a single-use ticket from your backend, then redeem it from the browser.Step A. Your backend mints the ticket:
// POST from your trusted server (Node, Python, anything)const resp = await fetch("https://api.opper.ai/v3/realtime-sessions", { method: "POST", headers: { Authorization: `Bearer ${process.env.OPPER_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ config: { model: "openai/gpt-realtime-2", voice: "marin", instructions: "You are a concise voice assistant.", }, }),});const { client_secret } = await resp.json();// Return client_secret to the browser.
Step B. The browser redeems it via subprotocol header:
const ws = new WebSocket( "wss://api.opper.ai/v3/realtime", [`opper-ticket.${clientSecret}`],);ws.onopen = () => { // Bound fields (model, voice, instructions) are already locked in // by the ticket. Send any remaining session.start fields here. ws.send(JSON.stringify({ type: "session.start", config: {} }));};ws.onmessage = (e) => { const ev = JSON.parse(e.data); // Handle session.started, audio.delta, tool.call, etc.};
Tickets are single-use and expire in 60 seconds by default. Whatever fields you populate in the mint request are locked, so the browser can’t override them. See Pre-binding for security.
From here, stream audio in with audio.append (base64-encoded PCM16 at input_sample_rate), and the assistant’s audio comes back in audio.delta frames at output_sample_rate. If a tool fires you get a tool.call and reply with tool.result. When the session ends you get session.terminating followed by a clean WebSocket close.
