GPT Realtime Usage Guide

This page describes how to use the Realtime model series (turing/gpt-realtime and turing/gpt-realtime-mini). It covers authentication, connection methods (WebSocket / HTTP), message format, Node.js / browser / Python examples, streaming event handling, common parameters, and best practices.

Overview

Realtime models are designed for low-latency, long-session, and streaming interactions. Typical use cases include live conversation, collaborative editing, real-time agents/assistants, and real-time speech-to-text with comprehension.

Key differences:

• turing/gpt-realtime: Full-featured, high-quality reasoning and generation. Suitable for scenarios requiring deep comprehension and long context.
• turing/gpt-realtime-mini: Lightweight, low-cost variant with lower latency. Suitable for high-concurrency and cost-sensitive scenarios, though it may underperform on complex reasoning tasks.

Authentication

All requests must include a Bearer token in the HTTP header:

• Header: Authorization: Bearer <YOUR_API_KEY>

Do not expose your primary API key on the client side. In browser environments, use a backend proxy or short-lived temporary credentials for all calls.

Choosing a Connection Method

• WebSocket (recommended): Best for low-latency, bidirectional real-time communication and scenarios requiring server-initiated event push. Supports multiplexed sessions, streaming responses, and sentence-by-sentence / token-by-token output.
• HTTP REST (polling or streaming): Suitable for one-off requests or environments where maintaining a persistent connection is impractical. HTTP streaming (chunked transfer) lets you receive generated output incrementally, but offers less flexibility for latency management and complex event handling compared to WebSocket.

Message Protocol (WebSocket)

The following JSON message format is recommended for WebSocket communication (shown as examples; refer to the backend documentation for the authoritative protocol):

• Client → Server (create session)

{
  "type": "session.create",
  "model": "turing/gpt-realtime",
  "session": {
    "id": "session-123",
    "metadata": { "user_id": "u-1" }
  }
}

• Client → Server (send input)

{
  "type": "input",
  "session_id": "session-123",
  "input": {
    "text": "Hello, please generate a product description in 50 words or fewer."
  }
}

• Server → Client (streaming output)

{
  "type": "output.token",
  "session_id": "session-123",
  "token": "Here",
  "seq": 1
}

{
  "type": "output.complete",
  "session_id": "session-123",
  "finished": true
}

Errors and status updates are also returned as events: error, session.closed, heartbeat, etc.

Node.js (WebSocket) Example

The following example uses the ws library to connect to the Realtime WebSocket. Replace WSS_URL and API_KEY with your actual values.

import WebSocket from 'ws';

const WSS_URL = 'wss://live-turing.cn.llm.tcljd.com/realtime';
const API_KEY = process.env.TURING_API_KEY;

const ws = new WebSocket(WSS_URL, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});

ws.on('open', () => {
  // Create session
  ws.send(JSON.stringify({ type: 'session.create', model: 'turing/gpt-realtime', session: { id: 's1' } }));
  // Send input
  ws.send(JSON.stringify({ type: 'input', session_id: 's1', input: { text: 'Write a job posting in around 40 words.' } }));
});

ws.on('message', (data) => {
  const msg = JSON.parse(data.toString());
  if (msg.type === 'output.token') process.stdout.write(msg.token);
  if (msg.type === 'output.complete') console.log('\n== Done ==');
  if (msg.type === 'error') console.error('Error:', msg.error);
});

ws.on('close', () => console.log('connection closed'));

Browser (via Backend Proxy)

It is recommended not to use your primary API key directly in the browser. Have your backend generate a temporary token or proxy the WebSocket connection. The example below assumes the backend returns wssUrl:

const ws = new WebSocket(wssUrl);
ws.addEventListener('open', () => {
  ws.send(JSON.stringify({ type: 'session.create', model: 'turing/gpt-realtime', session: { id: 'web-1' } }));
});

ws.addEventListener('message', (ev) => console.log('recv', JSON.parse(ev.data)));

Python (WebSocket) Example

Using the websockets or websocket-client library:

import os
import asyncio
import websockets
import json

WSS_URL = 'wss://live-turing.cn.llm.tcljd.com/realtime'
API_KEY = os.environ.get('TURING_API_KEY')

async def main():
    async with websockets.connect(WSS_URL, extra_headers={ 'Authorization': f'Bearer {API_KEY}' }) as ws:
        await ws.send(json.dumps({ 'type': 'session.create', 'model': 'turing/gpt-realtime', 'session': { 'id': 'py-1' } }))
        await ws.send(json.dumps({ 'type': 'input', 'session_id': 'py-1', 'input': { 'text': 'Please generate a product description in about 30 words.' } }))
        async for message in ws:
            msg = json.loads(message)
            if msg.get('type') == 'output.token':
                print(msg['token'], end='')
            if msg.get('type') == 'output.complete':
                print('\n-- done --')
                return

asyncio.run(main())

Common Parameters

• model: Model name (turing/gpt-realtime / turing/gpt-realtime-mini)
• max_tokens: Maximum generation length (in tokens)
• temperature: Sampling temperature (0–2)
• top_p: Nucleus sampling threshold
• stream: Whether to enable streaming output (HTTP)
• session.metadata: Session-level metadata (user ID, conversation topic, etc.)

Example:

{
  "model": "turing/gpt-realtime",
  "input": { "text": "Write a new-release announcement for customers." },
  "max_tokens": 300,
  "temperature": 0.2
}

Streaming Events and Reconnection

• Use heartbeat events to keep the connection alive. The server also sends session.keepalive or similar events.
• On a brief network disconnect, the client should save the session ID and the last sequence position (e.g., seq), then attempt to resume the session context using session.resume after reconnecting (if supported by the server).

Performance and Cost Recommendations

• If low latency and high concurrency are the primary requirements, prefer turing/gpt-realtime-mini combined with a shorter context window.
• When high-quality generation and complex reasoning are needed, use turing/gpt-realtime and tune max_tokens and temperature accordingly.

Troubleshooting and Debugging

• Cannot connect: Check the WSS URL, network connectivity, firewall rules, and the Authorization header. In browser environments, route requests through a backend proxy.
• Receiving error events: Inspect error.code and error.message. Common causes include authentication failures, quota exhaustion, and timeouts.
• Unstable or truncated output: Verify that the client correctly handles both output.token and output.complete events. When using HTTP chunked transfer, ensure chunks are concatenated in order.

Multi-Turn Conversation Management Tips

• Upload user and assistant history as session metadata, or let the server maintain session state, to avoid the bandwidth and latency overhead of sending the full context on every request.
• For very long histories, consider retaining only a summary or the most important turns to reduce token costs.

---

Changelog

• 2025-10-14: Added usage examples and best practices for turing/gpt-realtime and turing/gpt-realtime-mini.