Realtime voice API: gpt-realtime and Gemini Live over WebSocket
Your server exchanges its 1xai-* key for a client secret that lives 2 minutes, and your app opens a WebSocket with that secret. The relay passes the frames of the Realtime protocol through untouched, so turn detection, barge-in, live transcripts and function calling are the model's own. A call lasts up to 30 minutes and is billed after each of the model's turns. There is no WebRTC.
Last updated:
How it works
| Address | Purpose |
|---|---|
POST https://1xai.ir/v1/realtime/client_secret | Purpose:Mint a client secret with your API key |
wss://1xai.ir/rt/voice | Purpose:The socket that speaks the OpenAI Realtime protocol |
wss://1xai.ir/rt/gemini | Purpose:The socket that speaks the Gemini Live protocol |
This is the Realtime API itself, not a chain of speech-to-text, a language model and text-to-speech. The relay holds two sockets and passes frames through untouched; your client speaks the Realtime protocol directly. Voice passes through our server because a browser cannot reach the vendor directly from Iran, which is also why there is no WebRTC.
Step one: the key on the server, a secret on the client
The socket deliberately refuses an API key. Your server uses its key to mint a short-lived client secret and hands that to its own front end; what reaches the browser can only open a call, and it expires 2 minutes later. Losing a secret means a short window on one account; losing a key means the wallet.
curl -X POST https://1xai.ir/v1/realtime/client_secret \
-H "Authorization: Bearer $ONEXAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-realtime-mini"}' # optional; default gpt-realtime
# {
# "client_secret": { "value": "ek_...", "expires_at": 1756240000 },
# "model": "gpt-realtime-mini",
# "url": "wss://1xai.ir/rt/voice"
# }# Your backend. The API key lives here and only here.
import httpx
from fastapi import FastAPI
app = FastAPI()
@app.post("/voice-token")
async def voice_token():
async with httpx.AsyncClient() as http:
r = await http.post(
"https://1xai.ir/v1/realtime/client_secret",
headers={"Authorization": f"Bearer {ONEXAI_API_KEY}"},
)
r.raise_for_status()
return r.json() # hand straight to your front end- The model is chosen here, with
modelin the body (or?model=), and the secret opens only that model:gpt-realtime,gpt-realtime-mini,gpt-realtime-2.1-mini,gemini-3.1-flash-live-preview,gemini-3.8-live. The default isgpt-realtime. - Any other model answers
400with codemodel_not_supported. - Starting a call needs at least 2,000 Toman of spendable credit; under that the answer is
402. - The answer's
urlis the socket to open:/rt/voicefor the OpenAI models,/rt/geminifor the Gemini ones.
Step two: opening a call
A browser cannot set a header on a WebSocket handshake, so the secret travels in the query string; a server-side client has headers and should use one.
// Your page. Never sees the API key.
const { client_secret, url } = await fetch("/voice-token", { method: "POST" })
.then((r) => r.json());
const ws = new WebSocket(`${url}?client_secret=${client_secret.value}`);
ws.onopen = () => {
// Configure the session: voice, transcription, turn detection.
ws.send(JSON.stringify({
type: "session.update",
session: {
instructions: "Answer briefly.",
audio: {
input: {
format: "pcm16",
transcription: { model: "whisper-1" },
// Server-side VAD: the model decides when you stopped talking,
// and interrupting it cancels its reply (barge-in).
turn_detection: { type: "server_vad", interrupt_response: true },
},
output: { format: "pcm16", voice: "alloy" },
},
},
}));
};
ws.onmessage = (e) => {
const ev = JSON.parse(e.data);
switch (ev.type) {
case "conversation.item.input_audio_transcription.completed":
console.log("user said:", ev.transcript); // live transcript
break;
case "response.output_audio.delta":
playPCM(atob(ev.delta)); // model speaking
break;
case "response.function_call_arguments.done":
callYourBackend(ev.name, JSON.parse(ev.arguments)); // function calling
break;
case "error":
// insufficient_funds arrives here before the socket closes
console.error(ev.error);
break;
}
};
// Microphone in: base64 PCM16 frames, as they are captured.
function sendMic(pcm16) {
ws.send(JSON.stringify({ type: "input_audio_buffer.append", audio: pcm16 }));
}// Server-side client (no browser). A header instead of the query string:
// query strings reach access logs, headers do not.
import WebSocket from "ws";
const ws = new WebSocket("wss://1xai.ir/rt/voice", {
headers: { Authorization: `Bearer ${clientSecret}` },
});Step three: Gemini Live
For gemini-3.1-flash-live-preview or gemini-3.8-live, mint the client secret with that model; the answer returns wss://1xai.ir/rt/gemini. On that socket speak Google's own Live API: the first message is setup, and its model is replaced with the secret's. Google Search, Maps and URL context tools are removed; function calling and code execution stay. Each turn is billed when its usageMetadata arrives.
// Gemini Live: mint with {"model": "gemini-3.1-flash-live-preview"}
// (or "gemini-3.8-live"); the answer's url is wss://1xai.ir/rt/gemini.
// Then speak Google's Live API (BidiGenerateContent) as it is.
const ws = new WebSocket(`${url}?client_secret=${client_secret.value}`);
ws.onopen = () => {
// The first message must be the setup. Its "model" is replaced with the
// secret's; Google Search, Maps and URL context tools are removed
// (function calling and code execution are kept).
ws.send(JSON.stringify({
setup: {
model: "models/gemini-3.1-flash-live-preview",
generationConfig: { responseModalities: ["AUDIO"] },
systemInstruction: { parts: [{ text: "Answer briefly." }] },
inputAudioTranscription: {},
outputAudioTranscription: {},
},
}));
};
// Microphone in: base64 PCM16, 16 kHz mono.
function sendMic(pcm16) {
ws.send(JSON.stringify({
realtimeInput: { audio: { data: pcm16, mimeType: "audio/pcm;rate=16000" } },
}));
}
ws.onmessage = async (e) => {
const text = typeof e.data === "string" ? e.data : await e.data.text();
const msg = JSON.parse(text);
for (const part of msg.serverContent?.modelTurn?.parts ?? []) {
if (part.inlineData) playPCM(atob(part.inlineData.data)); // 24 kHz PCM16
}
// usageMetadata arrives with each turnComplete; that turn is billed then.
};Limits and cost
| What | Value |
|---|---|
| Transport | Value:WebSocket only; no WebRTC |
| Longest call | Value:30 minutes; then the socket is closed |
| Life of a client secret | Value:2 minutes from issue: enough to open the socket, not the length of the call |
| Credit needed to start | Value:2,000 Toman; a call is cut with an insufficient_funds event when the spendable credit falls under that |
| Sessions | Value:Each socket is its own session; nothing is shared between calls |
- Audio tokens are billed apart from text, at the vendor's own audio rate plus the model's markup (20% for the realtime models), and cost several times as much as text. The current rates are on the pricing page.
- Cached audio (the earlier conversation, re-read on every turn) is billed at the vendor's cached rate, which is far cheaper than fresh audio.
- Transcription of the input audio, when you switch it on, is billed separately at the transcription model's rate. Allowed models:
whisper-1,gpt-4o-transcribe,gpt-4o-mini-transcribe,gpt-realtime-whisperandgpt-live-transcribe. - The call is settled after each of the model's responses, not at the end of the call.
- No audio is kept: a realtime usage row has no request or response text.
Questions
Is WebRTC supported?
No, only WebSocket. WebRTC is a direct connection from the browser to the vendor's server, which is exactly what does not work from inside Iran; the voice has to pass through our server.
Why a client secret instead of the API key on the socket?
Because an API key spends from your wallet, and in client-side JavaScript it is in every visitor's developer tools. The socket accepts only an ek_ value; it lives 2 minutes and can only open a call.
Which models can I choose?
gpt-realtime (the default), gpt-realtime-mini and gpt-realtime-2.1-mini on /rt/voice with the OpenAI protocol; gemini-3.1-flash-live-preview and gemini-3.8-live on /rt/gemini with the Gemini Live protocol.
1xAi is an independent gateway. It is not affiliated with, endorsed by, or a reseller for OpenAI, Anthropic, Google, DeepSeek, xAI, Moonshot AI, Z.ai, Alibaba Qwen, MiniMax or Tencent Hunyuan. Requests are relayed upstream rather than answered by models of our own, so each provider's own usage policies apply to what their models will and will not do, and their model availability is theirs to change. Current reachability is published on the status page.