RealtimeVoiceConversation

RealtimeVoiceConversation is the browser-side helper for Speko speech-to-speech (S2S) sessions. POST /v1/sessions reserves credit and returns a short-lived provider credential; the browser then connects directly to OpenAI, xAI, or Gemini Live. Realtime audio does not pass through a Speko media proxy.

Use it when you want the lowest-latency S2S path and do not need the browser media transport used by VoiceConversation.

import { RealtimeVoiceConversation } from '@spekoai/client';

Mint the session on your server

Create S2S sessions on your backend so SPEKO_API_KEY never reaches the browser. Return the provider-direct response unchanged; it contains only a scoped, short-lived provider credential plus Speko telemetry and billing-control URLs.

app.post('/api/realtime-session', async (req, res) => {
  // Preserve this value if your server retries an ambiguous upstream timeout.
  const idempotencyKey = req.get('Idempotency-Key') || crypto.randomUUID();
  const response = await fetch('https://api.speko.dev/v1/sessions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SPEKO_API_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey,
    },
    body: JSON.stringify({
      mode: 's2s',
      s2s: {
        provider: 'openai',
        model: 'gpt-realtime-2.1',
        voice: 'marin',
        systemPrompt: 'You are a concise voice assistant.',
      },
      ttlSeconds: 900,
    }),
  });

  if (!response.ok) {
    res.status(response.status).json({ error: 'Could not start realtime session' });
    return;
  }

  res.json(await response.json());
});

Connect from the browser

import { useEffect, useRef, useState } from 'react';
import { RealtimeVoiceConversation } from '@spekoai/client';

export function RealtimePanel() {
  const convRef = useRef<RealtimeVoiceConversation | null>(null);
  const [status, setStatus] = useState('idle');
  const [transcript, setTranscript] = useState<string[]>([]);

  async function start() {
    setStatus('connecting');
    const session = await fetch('/api/realtime-session', {
      method: 'POST',
    }).then((r) => r.json());

    const conv = await RealtimeVoiceConversation.create({
      ...session,
      onConnect: ({ conversationId }) => {
        console.log('connected', conversationId);
      },
      onStatusChange: setStatus,
      onMessage: ({ source, text, isFinal }) => {
        if (isFinal) setTranscript((items) => [...items, `${source}: ${text}`]);
      },
      onError: (err) => console.error(err),
      onDisconnect: () => setStatus('idle'),
    });

    convRef.current = conv;
  }

  async function stop() {
    await convRef.current?.endSession();
    convRef.current = null;
  }

  useEffect(() => () => { void convRef.current?.endSession(); }, []);

  return (
    <div>
      <button onClick={start} disabled={status !== 'idle'}>Start</button>
      <button onClick={stop} disabled={status === 'idle'}>Stop</button>
      <p>Status: {status}</p>
      <ul>{transcript.map((item, i) => <li key={i}>{item}</li>)}</ul>
    </div>
  );
}