Realtime Voice 完全指南：gpt-realtime 与 Voice Mode

GPT-Realtime-2.1 是 OpenAI 2026-07-06 发布的低延迟语音模型，能直接处理输入音频流并实时生成语音回复，端到端延迟约 300ms；GPT-Realtime-2.1-mini 是低成本变体。两者通过 Realtime API 暴露给开发者，是 ChatGPT Voice Mode 的底层引擎。

1. 概述

Realtime API 与 ChatGPT Voice Mode 共用同一个 GPT-Realtime-2.1 模型族，但面向不同消费者：Voice Mode 是 ChatGPT 应用内置的产品功能，Realtime API 是面向开发者的接口，通过 WebRTC 或 WebSocket 暴露模型，让你做自己的语音产品。本文覆盖两者差别、WebRTC / WebSocket 选型、ephemeral token 鉴权、以及 mid-conversation function calling 的完整实战。所有代码基于 Realtime API 2026-07 版本，参考 OpenAI 官方 WebRTC 指南。

2. 核心要点

• 模型族：GPT-Realtime-2.1（旗舰）和 GPT-Realtime-2.1-mini（低成本），2026-07-06 发布。旧版 Realtime API Beta 已于 2026-05-12 下线。
• Transport 选型：浏览器端用 WebRTC（点对点、低延迟、浏览器自带音频管线）；服务端中转或需要全控音频流用 WebSocket（便于日志、转码、编排）。
• 鉴权：生产部署必须用 ephemeral token（短期 client secret），永远不要把长期 API Key 发到浏览器。
• Function Calling：支持 mid-conversation function calling，可以在语音对话中调用天气、订单、日历等工具，不打断对话流。
• 音色：内置十种音色——alloy、ash、ballad、coral、echo、sage、shimmer、verse、marin、cedar；可调 temperature 控制语气变化。

3. 工作机制

Realtime API 是一个双向流式协议。核心流程分三步：

1. 创建 Session：你的服务端用长期 API Key 调 POST /v1/realtime/sessions，拿到一个 ephemeral client secret（有效期约 1 分钟）和 session 配置（model、voice、instructions、tools 等）。
2. 建立连接：浏览器用 ephemeral secret 通过 WebRTC（SDP offer/answer 交换）或 WebSocket 连到 OpenAI；连接建立后，音频流双向传输。
3. 双向音频流：用户麦克风音频流进模型，模型实时生成语音回复流回来；function call 事件在对话中间异步触发。

关键区别于传统 Chat Completions API：Realtime API 不是"请求→响应"模式，而是持续的双向流——你在对话的任意时刻发送音频、文本、function call 结果，模型也会在任意时刻返回音频、文本、function call 请求。

4. 实战步骤

4.1 服务端：签发 ephemeral token

永远不要把长期 API Key 嵌进前端代码。你的服务端用真实 Key 换一个短时 token 交给浏览器：

from openai import OpenAI

client = OpenAI()  # 自动读取 OPENAI_API_KEY

# 创建一个 ephemeral session，拿到短时 client secret
session = client.beta.realtime.sessions.create(
    model="gpt-realtime-2.1",
    voice="alloy",
    instructions="你是 GPTMap 的语音助手，用简洁的中文回答。",
)

# 只把 client_secret.value 传给浏览器——它几分钟内过期且不可复用
ephemeral_token = session.client_secret.value
print(ephemeral_token)
# 把这个 token 返回给前端（通过你的 API endpoint）

client_secret 默认 600 秒（10 分钟）过期，范围 10-7200 秒。浏览器拿到后立即用它建连，不要存储。

4.2 浏览器：WebRTC 连接

浏览器端用 ephemeral token 建立 WebRTC peer connection。以下是最小可用示例：

// 1. 从你的服务端拿 ephemeral token
const response = await fetch("/api/realtime-token");
const { token } = await response.json();

// 2. 创建 peer connection 并建连
const pc = new RTCPeerConnection();

// 把本地麦克风流加到 connection
const localStream = await navigator.mediaDevices.getUserMedia({ audio: true });
localStream.getTracks().forEach((track) => pc.addTrack(track));

// 3. 用 ephemeral token 做 SDP offer/answer 交换
const dc = pc.createDataChannel("oai-events");

const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

// SDP 端点接收的是原始 SDP 文本，不是 JSON
const sdpResponse = await fetch(
  "https://api.openai.com/v1/realtime/calls",
  {
    method: "POST",
    body: offer.sdp,  // 原始 SDP 文本
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/sdp",
    },
  }
);
const answerSdp = await sdpResponse.text();
await pc.setRemoteDescription({ type: "answer", sdp: answerSdp });

// 4. 播放模型返回的音频
pc.ontrack = (e) => {
  const audio = new Audio();
  audio.srcObject = e.streams[0];
  audio.play();
};

// 5. 通过 data channel 收发事件（function call、transcription 等）
dc.onmessage = (e) => {
  const event = JSON.parse(e.data);
  console.log("Realtime event:", event.type);
};

4.3 对话中的 Function Calling

在创建 session 时声明 tools，模型在对话中需要某个工具时会自动触发 function call：

session = client.beta.realtime.sessions.create(
    model="gpt-realtime-2.1",
    voice="alloy",
    tools=[
        {
            "type": "function",
            "name": "get_weather",
            "description": "查询指定城市的当前天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名"},
                },
                "required": ["city"],
            },
        }
    ],
)

连接后，当用户说"北京天气怎么样"，模型会通过 data channel 发出 function_call 事件，你的代码执行 get_weather("北京") 并把结果通过 conversation.item.create 返回，模型会把结果融进语音回复——用户只听到答案，听不到 function call 过程。

4.4 选择音色与调温度

session = client.beta.realtime.sessions.create(
    model="gpt-realtime-2.1",
    voice="nova",        # 温暖、偏女性音色
    temperature=0.8,     # 0.6 保守 / 0.8 平衡 / 1.0 更有表现力
    input_audio_transcription={
        "model": "gpt-realtime-whisper"  # 服务端转写，便于审计
    },
)

十种音色按风格分类：沉稳型（alloy、echo）、明亮型（coral、marin、sage、verse）、叙事型（ash、ballad、cedar、shimmer）。

5. 常见错误与排查

6. 下一步

掌握 Realtime API 后，建议继续阅读：

• 《ChatGPT 完全指南（2026）：从入门到精通》—— Voice Mode 消费端深度使用
• 《OpenAI API 入门：第一个 GPT-5.6 调用详解》—— Responses API 文本流基础
• 《GPT 模型完全指南（2026-07）：GPT-5.6 Sol / Terra / Luna》—— 模型选型全景