OpenAI Realtime API 技术原理与实践指南

一、概述

OpenAI Realtime API 旨在实现低延迟的多模态人机交互，支持包括语音对话、实时转录等场景。此接口能够与多模态模型（如 GPT-4o 和 GPT-4o mini）协同工作，实现实时文本与音频处理、函数调用（function calling）及语音生成等功能。同时，配合最新的转录模型（如 GPT-4o Transcribe 和 GPT-4o mini Transcribe），可满足多样化的实时语音处理需求。

二、典型应用场景

• 实时语音对话系统（speech-to-speech）
• 实时语音转录与分析
• 语音活动检测（VAD）与自动会话轮次控制
• 多模态数据流的实时处理和交互

三、核心技术与架构解析

3.1 连接方式

Realtime API 支持两种主要的连接方式：

• WebRTC：适用于浏览器或客户端应用，能高效捕获本地音频并接收远端音频流。
• WebSocket：适用于后端服务器之间实时通信，便于服务端集成及扩展。

3.2 安全认证机制

• 标准 API Key：仅推荐在安全的服务端环境使用。
• 临时（Ephemeral）API Key：主要用于客户端场景，由后端服务动态生成，有效期短，减少密钥泄漏风险。

四、使用 WebRTC 接入 Realtime API

4.1 技术原理

WebRTC（Web Real-Time Communication）是一套支持实时音视频交互的开放协议。通过与 Realtime API 的 PeerConnection 建立安全的数据通道和音频流，实现实时语音交互。

4.2 关键参数配置

• 服务端地址：https://zzzzapi.com/v1/realtime
• 查询参数：model（如 gpt-4o-realtime-preview-2025-06-03）
• 认证头部：Authorization: Bearer EPHEMERAL_KEY

4.3 客户端连接流程示例

// 基于浏览器的 WebRTC 连接示例，需先从后端获取临时 API Key。
async function init() {
    // 步骤1：从后端获取临时 API Key
    const tokenResponse = await fetch('/session');
    const data = await tokenResponse.json();
    const EPHEMERAL_KEY = data.client_secret.value;

    // 步骤2：新建 RTCPeerConnection 实例
    const pc = new RTCPeerConnection();

    // 步骤3：设置远端音频流播放
    const audioEl = document.createElement('audio');
    audioEl.autoplay = true;
    pc.ontrack = (e) => {
        audioEl.srcObject = e.streams[0];
    };

    // 步骤4：添加本地麦克风音频轨道
    const ms = await navigator.mediaDevices.getUserMedia({ audio: true });
    pc.addTrack(ms.getTracks()[0]);

    // 步骤5：建立数据通道用于事件通信
    const dc = pc.createDataChannel('oai-events');
    dc.addEventListener('message', (e) => {
        // 处理来自 Realtime API 的事件消息
        console.log(e.data);
    });

    // 步骤6：启动 SDP 信令流程
    const offer = await pc.createOffer();
    await pc.setLocalDescription(offer);
    const baseUrl = 'https://zzzzapi.com/v1/realtime';
    const model = 'gpt-4o-realtime-preview-2025-06-03';
    const sdpResponse = await fetch(`${baseUrl}?model=${model}`, {
        method: 'POST',
        body: offer.sdp,
        headers: {
            'Authorization': `Bearer ${EPHEMERAL_KEY}`,
            'Content-Type': 'application/sdp',
        },
    });
    const answer = {
        type: 'answer',
        sdp: await sdpResponse.text(),
    };
    await pc.setRemoteDescription(answer);
}

// 初始化会话
init();

4.4 生成临时 API Key 的服务端示例

// 基于 Node.js Express 的临时 Key 生成服务
import express from 'express';
const app = express();

// 提供 `/session` 接口，返回 OpenAI Realtime 临时 API Key
app.get('/session', async (req, res) => {
    const r = await fetch('https://zzzzapi.com/v1/realtime/sessions', {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer ' + process.env.OPENAI_API_KEY,
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            model: 'gpt-4o-realtime-preview-2025-06-03',
            voice: 'verse',
        }),
    });
    const data = await r.json();
    res.send(data);
});
app.listen(3000);

注意：请确保标准 API Key 仅用于服务端，避免泄漏。

五、使用 WebSocket 接入 Realtime API

5.1 技术原理

WebSocket 协议可实现服务器与客户端之间的全双工通信，适合后端与 OpenAI Realtime API 间的低延迟数据交换。

5.2 关键参数配置

• 服务端地址：wss://zzzzapi.com/v1/realtime?model=gpt-4o-realtime-preview-2025-06-03
• 认证头部：Authorization: Bearer YOUR_API_KEY
• 版本标识头：OpenAI-Beta: realtime v1（如处于 beta 阶段时）

5.3 Node.js 服务端连接示例

import WebSocket from 'ws';
const url = 'wss://zzzzapi.com/v1/realtime?model=gpt-4o-realtime-preview-2025-06-03';
const ws = new WebSocket(url, {
    headers: {
        'Authorization': 'Bearer ' + process.env.OPENAI_API_KEY,
        'OpenAI-Beta': 'realtime v1',
    },
});

ws.on('open', function open() {
    console.log('已连接到 Realtime API。');
});

ws.on('message', function incoming(message) {
    // 处理实时事件消息
    console.log(JSON.parse(message.toString()));
});

六、技术要点及实践建议

• 客户端场景请务必使用临时（ephemeral）API Key，避免密钥泄漏。
• 标准 API Key 仅应配置在受控服务器环境。
• 音频流与事件数据的编解码需遵循 WebRTC/WebSocket 相关标准。
• 合理配置声学前端与音频采样，提升对话体验与转录准确性。

七、结语

OpenAI Realtime API 提供了高效的实时多模态交互能力，适用于语音对话、实时转录等典型场景。通过灵活选择 WebRTC 或 WebSocket 连接方式，可根据不同应用需求构建安全可靠的实时语音处理系统。