Realtime voice sessions

​

Models

​

How it works

1. Mint a session credential — one API call that authenticates you, reserves funds, selects the model and voice, and returns a short-lived ephemeral_key and wss_url.
2. Connect your WebSocket directly to wss_url using ephemeral_key. Drive the session with audio I/O events only.

​

Step 1: Mint a session

• grok-voice — any built-in voice ID from GET /v1/voices (e.g. "ara", "atlas", "luna") with no extra org gate, or one of your organization’s custom voice IDs from GET /v1/custom-voices, which requires the customVoicesEnabled org gate in addition to realtimeVoiceEnabled. Defaults to "ara".
• eleven-realtime-v1-mini / eleven-realtime-v1-max — an ElevenLabs voice ID (1–64 characters). Defaults to "brian". GET /v1/voices and custom voice clones are xAI-only and are not accepted on Eleven Realtime sessions.

curl -X POST https://api.aireserve.com/v1/realtime/sessions \
  -H "Authorization: Bearer $AIRESERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-voice", "voice": "ara"}'

const response = await fetch("https://api.aireserve.com/v1/realtime/sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AIRESERVE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ model: "grok-voice", voice: "ara" }),
});
const session = await response.json();

import os, requests

session = requests.post(
    "https://api.aireserve.com/v1/realtime/sessions",
    headers={"Authorization": f"Bearer {os.environ['AIRESERVE_API_KEY']}"},
    json={"model": "grok-voice", "voice": "ara"},
).json()

curl -X POST https://api.aireserve.com/v1/realtime/sessions \
  -H "Authorization: Bearer $AIRESERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "eleven-realtime-v1-mini", "voice": "brian"}'

{
  "session_id": "9c3f1a2b-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "model": "grok-voice",
  "voice": "ara",
  "wss_url": "wss://voice-relay-uat-abcdefg-ue.a.run.app/v1/realtime?model=grok-voice",
  "ephemeral_key": "v1.1756946700.ABCDEFGHIJKLMNOPQRSTuvwxyz01234.signature_base64url_43chars",
  "expires_at": "2026-09-03T21:05:00.000Z",
  "key_ttl_seconds": 300,
  "max_session_seconds": 3540,
  "browser_subprotocols": [
    "openai-beta.realtime-v1",
    "openai-insecure-api-key.v1.1756946700.ABCDEFGHIJKLMNOPQRSTuvwxyz01234.signature_base64url_43chars"
  ]
}

​

Step 2: Connect the WebSocket

GET <wss_url returned by POST /v1/realtime/sessions>
Authorization: Bearer <ephemeral_key>

const ws = new WebSocket(session.wss_url, session.browser_subprotocols);

​

Using the OpenAI Realtime SDK

import { OpenAIRealtimeWebSocket, RealtimeAgent, RealtimeSession } from "@openai/agents-realtime";

// Your backend calls POST /v1/realtime/sessions with model "eleven-realtime-v1-mini"
// and returns the 201 body; the AI Reserve API key never leaves the server.
const minted = await fetch("/api/voice-session", { method: "POST" }).then((r) => r.json());

const agent = new RealtimeAgent({
  name: "Concierge",
  instructions: "Answer briefly and warmly.",
});
const transport = new OpenAIRealtimeWebSocket({
  url: minted.wss_url, // the relay; used verbatim, the model is already bound
  // Browsers: the SDK only accepts ephemeral `ek_` keys unless told the key is
  // short-lived. The relay ticket is; it rides the WebSocket subprotocol.
  useInsecureApiKey: true,
});
const session = new RealtimeSession(agent, { transport });

await session.connect({ apiKey: minted.ephemeral_key });

​

Supported WebSocket events

​

Available voices

​

Billing and limits

​

Audio persistence

​

Enable realtime voice

1. Contact your AI Reserve representative (or the Help page in the portal) to enable realtimeVoiceEnabled for your organization.
2. Optionally enable customVoicesEnabled if you want to use custom voice clones in grok-voice sessions, and have an administrator accept the unverified-retention opt-in if you want the Eleven Realtime models.
3. Mint a session and connect — the two-step flow above is the full integration.
4. Watch your usage dashboard: each session appears as one audio usage row with duration and cost.

​

Deferred features

• Standalone speech-to-text: transcription calls without voice synthesis. See POST /v1/audio/transcriptions for the existing OpenAI-compatible transcription endpoint.
• Streaming TTS: text-in, audio-out streaming without a microphone. See POST /v1/audio/speech for synchronous (non-streaming) TTS with grok-tts.
• SIP / telephony and WebRTC: sessions are WebSocket only; direct PSTN or SIP dial-in/dial-out and WebRTC transports are not available.
• Tool calling in realtime sessions: function calling over the realtime session is not yet available on any model.
• Session resumption: each POST /v1/realtime/sessions mint starts a fresh session; reconnecting to a prior session is not supported.