IN ENGLISH · API DOCS

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:

[01]REALTIME VOICE

How it works

The three addresses
AddressPurpose
POST https://1xai.ir/v1/realtime/client_secretPurpose:Mint a client secret with your API key
wss://1xai.ir/rt/voicePurpose:The socket that speaks the OpenAI Realtime protocol
wss://1xai.ir/rt/geminiPurpose: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.

[02]REALTIME VOICE

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.

POST /v1/realtime/client_secret · Minting a client secretcurl
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"
# }
On your serverpython (fastapi)
# 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 model in 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 is gpt-realtime.
  • Any other model answers 400 with code model_not_supported.
  • Starting a call needs at least 2,000 Toman of spendable credit; under that the answer is 402.
  • The answer's url is the socket to open: /rt/voice for the OpenAI models, /rt/gemini for the Gemini ones.
[03]REALTIME VOICE

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.

wss://1xai.ir/rt/voice · In the browserjavascript
// 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 }));
}
A server-side clientnode
// 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}` },
});
[04]REALTIME VOICE

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.

wss://1xai.ir/rt/gemini · Gemini Livejavascript
// 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.
};
[05]REALTIME VOICE

Limits and cost

Limits of a realtime call
WhatValue
TransportValue:WebSocket only; no WebRTC
Longest callValue:30 minutes; then the socket is closed
Life of a client secretValue:2 minutes from issue: enough to open the socket, not the length of the call
Credit needed to startValue:2,000 Toman; a call is cut with an insufficient_funds event when the spendable credit falls under that
SessionsValue: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-whisper and gpt-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.
[06]REALTIME VOICE

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.