网站导航
> 技术文档 > OpenAI Realtime API 详解：构建低延迟多模态交互体验（Beta版）

OpenAI Realtime API 详解：构建低延迟多模态交互体验（Beta版）

网友: 技术文档 2025-09-04 00:40:51

OpenAI Realtime API 详解：构建低延迟多模态交互体验（Beta版）

在实时交互场景日益丰富的今天，低延迟、多模态的交互体验已成为开发者的核心需求。OpenAI推出的Realtime API（Beta版）正是为解决这一需求而生，它支持构建语音对话、实时转录等低延迟多模态交互场景。在实际开发中，开发者可通过稳定的API中转站（如https://link.ywhttp.com/foA8Wb）更便捷地接入服务，提升开发效率。

Realtime API 核心能力

OpenAI Realtime API 赋能开发者构建低延迟的多模态交互场景，包括语音到语音的对话体验、实时转录等功能。该API兼容原生多模态模型，主要支持以下模型及能力：

  • 核心模型：如GPT-4o、GPT-4o mini，提供实时文本与音频处理、函数调用、语音生成等能力；
  • 转录模型：最新的GPT-4o Transcribe、GPT-4o mini Transcribe，专注于高精度实时转录。

快速上手 Realtime API

刚接触Realtime API？推荐尝试新的TypeScript Agents SDK，它专为基于Realtime模型构建语音代理优化。

Realtime API 支持两种连接方式，开发者可根据场景选择：

  • WebRTC：适用于客户端应用（如Web应用），擅长处理网络状态变化，提供便捷的音频捕获与播放API；
  • WebSockets：适用于服务器到服务器的应用（如后端服务或电话语音代理），支持稳定的实时数据传输。

下面将从示例应用、合作伙伴集成、连接方式等方面展开介绍，帮助开发者快速接入。

示例应用参考

以下示例应用可直观展示Realtime API的实际效果，开发者可直接参考实现逻辑：

  • Realtime Console
    快速入门工具，下载并配置后可实时查看事件流转，解析事件内容，学习如何通过函数调用执行自定义逻辑。查看详情

  • Realtime Solar System Demo
    基于WebRTC集成的演示，通过语音指令结合函数调用实现太阳系导航交互。查看详情

  • Twilio Integration Demo
    结合Realtime API与Twilio构建AI通话助手的示例。查看详情

  • Realtime API Agents Demo
    展示Realtime API语音代理之间的切换能力，包含推理模型验证逻辑。查看详情

合作伙伴集成方案

Realtime API已与多个主流平台完成集成，覆盖前端应用、电话通信等场景，开发者可直接参考以下集成指南：

  • LiveKit 集成指南：如何结合Realtime API与LiveKit的WebRTC基础设施。查看详情
  • Twilio 集成指南：利用Twilio强大的语音API构建Realtime应用。查看详情
  • Agora 集成快速入门：将Agora的实时音频通信能力与Realtime API集成。查看详情
  • Pipecat 集成指南：通过Pipecat编排框架与OpenAI音频模型构建语音代理。查看详情
  • Stream 集成指南：基于Stream的全球边缘网络在移动和Web应用中部署语音代理。查看详情

核心应用场景

Realtime API的典型应用场景主要分为两类，开发者可根据需求选择对应的初始化方式：

1. 实时语音到语音对话

适用于构建语音代理及其他语音交互应用，支持实时的语音输入与生成，实现自然流畅的对话体验。

2. 实时转录

专注于转录场景，客户端可流式传输音频，Realtime API会在检测到语音时生成流式转录文本，支持按语句分析转录内容。

两种场景均内置语音活动检测（VAD） 能力，可自动识别用户说话结束的时机，无缝处理对话轮次或转录分段。如需深入了解，可参考专项指南：

  • 实时语音到语音对话指南
  • 实时转录指南

通过 WebRTC 连接 Realtime API

WebRTC 是一套强大的实时应用标准接口，OpenAI Realtime API 支持通过WebRTC对等连接接入实时模型。以下是连接配置指南。

适用场景与优势

当需要从非安全客户端（如Web浏览器）通过网络连接Realtime模型时，推荐使用WebRTC方式。其优势在于：

  • 更好地处理不稳定的网络状态；
  • 提供便捷的API用于捕获用户音频输入和播放模型返回的音频流。

连接流程（以Web浏览器为例）

浏览器连接Realtime API需使用临时API密钥（通过OpenAI REST API生成），流程如下：

  1. 浏览器向开发者控制的服务器请求生成临时API密钥；
  2. 开发者服务器使用标准API密钥通过OpenAI REST API请求临时密钥，并返回给浏览器（注：临时密钥当前有效期为1分钟）；
  3. 浏览器使用临时密钥通过WebRTC对等连接直接与OpenAI Realtime API建立会话。

注意：虽然技术上可使用标准API密钥在客户端认证WebRTC会话，但这是不安全的做法（会泄露密钥）。标准API密钥拥有OpenAI API账户的完整访问权限，仅应在安全的服务器环境中使用。客户端应用建议优先使用临时密钥。

连接配置详情

通过WebRTC连接需以下配置信息：

配置项 内容 URL https://api.aaaaapi.com/v1/realtime 查询参数 model：需连接的实时模型ID，如gpt-4o-realtime-preview-2025-06-03 请求头 Authorization: Bearer EPHEMERAL_KEY（替换为临时API令牌，生成方式见下文）

WebRTC 初始化示例代码

以下示例展示如何初始化WebRTC会话（包括用于发送和接收Realtime API事件的数据通道），假设已获取临时API令牌（服务器端生成代码见下一节）：

async function init() { // 从服务器获取临时密钥（见下方服务器代码） const tokenResponse = await fetch(\"/session\"); const data = await tokenResponse.json(); const EPHEMERAL_KEY = data.client_secret.value; // 创建对等连接 const pc = new RTCPeerConnection(); // 配置播放模型返回的远程音频 const audioEl = document.createElement(\"audio\"); audioEl.autoplay = true; pc.ontrack = e => audioEl.srcObject = e.streams[0]; // 添加浏览器麦克风的本地音频轨道 const ms = await navigator.mediaDevices.getUserMedia({ audio: true }); pc.addTrack(ms.getTracks()[0]); // 配置数据通道用于发送和接收事件 const dc = pc.createDataChannel(\"oai-events\"); dc.addEventListener(\"message\", (e) => { // 实时服务器事件将在这里接收！ console.log(e); }); // 使用会话描述协议（SDP）启动会话 const offer = await pc.createOffer(); await pc.setLocalDescription(offer); const baseUrl = \"https://api.aaaaapi.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();

WebRTC API提供了丰富的媒体流和输入设备控制能力，如需构建基于WebRTC的用户界面，可参考MDN文档。

生成临时令牌（服务器端实现）

为在客户端使用临时令牌，需构建服务器端应用（或集成到现有服务），通过OpenAI REST API请求临时密钥。服务器端需使用标准API密钥认证请求。

以下是基于Node.js express的简单服务器示例，用于生成临时API密钥：

import express from \"express\";const app = express();// 与客户端代码配合的接口，返回OpenAI REST API的响应内容app.get(\"/session\", async (req, res) => { const r = await fetch(\"https://api.aaaaapi.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(); // 将OpenAI REST API返回的JSON发送给客户端 res.send(data);});app.listen(3000);

可在任何支持HTTP请求的平台实现类似服务器接口，确保仅在服务器端使用标准OpenAI API密钥，而非浏览器端。如需更稳定的服务接入，可通过API中转站获取额外支持。

事件发送与接收

如需了解如何通过WebRTC数据通道发送和接收事件，可参考实时对话指南。

通过 WebSockets 连接 Realtime API

WebSockets 是广泛支持的实时数据传输API，是服务器到服务器应用连接OpenAI Realtime API的理想选择。对于浏览器和移动客户端，建议优先使用WebRTC。

适用场景与优势

在服务器到服务器的集成中，后端系统可通过WebSocket直接连接Realtime API。此时可使用标准API密钥认证（密钥仅在安全的后端环境中可用）。

WebSocket连接也可使用临时客户端令牌（如WebRTC部分所示）在客户端设备连接，但标准OpenAI API令牌仅应在安全的服务器端环境使用。

连接配置详情（语音到语音场景）

通过WebSocket连接需以下配置信息：

配置项 内容 URL wss://api.aaaaapi.com/v1/realtime 查询参数 model：需连接的实时模型ID，如gpt-4o-realtime-preview-2024-12-17 请求头 Authorization: Bearer YOUR_API_KEY（服务器端使用标准API密钥，非安全客户端使用临时令牌）；OpenAI-Beta: realtime=v1（Beta期间必填）
WebSocket 初始化示例代码

以下是不同语言的WebSocket连接示例：

Node.js（ws模块）

import WebSocket from \"ws\";const url = \"wss://api.aaaaapi.com/v1/realtime?model=gpt-4o-realtime-preview-2024-12-17\";const ws = new WebSocket(url, { headers: { \"Authorization\": \"Bearer \" + process.env.OPENAI_API_KEY, \"OpenAI-Beta\": \"realtime=v1\", },});ws.on(\"open\", function open() { console.log(\"已连接到服务器。\");});ws.on(\"message\", function incoming(message) { console.log(JSON.parse(message.toString()));});

Python（websocket-client）

# 示例需安装websocket-client库：pip install websocket-clientimport osimport jsonimport websocketOPENAI_API_KEY = os.environ.get(\"OPENAI_API_KEY\")url = \"wss://api.aaaaapi.com/v1/realtime?model=gpt-4o-realtime-preview-2024-12-17\"headers = [ \"Authorization: Bearer \" + OPENAI_API_KEY, \"OpenAI-Beta: realtime=v1\"]def on_open(ws): print(\"已连接到服务器。\")def on_message(ws, message): data = json.loads(message) print(\"收到事件：\", json.dumps(data, indent=2))ws = websocket.WebSocketApp( url, header=headers, on_open=on_open, on_message=on_message,)ws.run_forever()

浏览器端 WebSocket

/*注意：在浏览器等客户端环境中，建议优先使用WebRTC。但在Deno、Cloudflare Workers等类浏览器环境中，可使用标准WebSocket接口。*/const ws = new WebSocket( \"wss://api.aaaaapi.com/v1/realtime?model=gpt-4o-realtime-preview-2024-12-17\", [ \"realtime\", // 认证信息 \"openai-insecure-api-key.\" + OPENAI_API_KEY, // 可选信息 \"openai-organization.\" + OPENAI_ORG_ID, \"openai-project.\" + OPENAI_PROJECT_ID, // Beta协议，必填 \"openai-beta.realtime-v1\" ]);ws.on(\"open\", function open() { console.log(\"已连接到服务器。\");});ws.on(\"message\", function incoming(message) { console.log(message.data);});

连接配置详情（转录场景）

转录场景的WebSocket连接配置如下：

配置项 内容 URL wss://api.aaaaapi.com/v1/realtime 查询参数 intent：连接意图，固定为transcription 请求头 Authorization: Bearer YOUR_API_KEY（服务器端使用标准API密钥，非安全客户端使用临时令牌）；OpenAI-Beta: realtime=v1（Beta期间必填）
转录场景 WebSocket 初始化示例代码

Node.js（ws模块）

import WebSocket from \"ws\";const url = \"wss://api.aaaaapi.com/v1/realtime?intent=transcription\";const ws = new WebSocket(url, { headers: { \"Authorization\": \"Bearer \" + process.env.OPENAI_API_KEY, \"OpenAI-Beta\": \"realtime=v1\", },});ws.on(\"open\", function open() { console.log(\"已连接到服务器。\");});ws.on(\"message\", function incoming(message) { console.log(JSON.parse(message.toString()));});

Python（websocket-client）

import osimport jsonimport websocketOPENAI_API_KEY = os.environ.get(\"OPENAI_API_KEY\")url = \"wss://api.aaaaapi.com/v1/realtime?intent=transcription\"headers = [ \"Authorization: Bearer \" + OPENAI_API_KEY, \"OpenAI-Beta: realtime=v1\"]def on_open(ws): print(\"已连接到服务器。\")def on_message(ws, message): data = json.loads(message) print(\"收到事件：\", json.dumps(data, indent=2))ws = websocket.WebSocketApp( url, header=headers, on_open=on_open, on_message=on_message,)ws.run_forever()

浏览器端 WebSocket

/*注意：在浏览器等客户端环境中，建议优先使用WebRTC。但在Deno、Cloudflare Workers等类浏览器环境中，可使用标准WebSocket接口。*/const ws = new WebSocket( \"wss://api.aaaaapi.com/v1/realtime?intent=transcription\", [ \"realtime\", // 认证信息 \"openai-insecure-api-key.\" + OPENAI_API_KEY, // 可选信息 \"openai-organization.\" + OPENAI_ORG_ID, \"openai-project.\" + OPENAI_PROJECT_ID, // Beta协议，必填 \"openai-beta.realtime-v1\" ]);ws.on(\"open\", function open() { console.log(\"已连接到服务器。\");});ws.on(\"message\", function incoming(message) { console.log(message.data);});

事件发送与接收

如需了解如何通过WebSocket发送和接收事件，语音到语音场景可参考实时对话指南，转录场景可参考实时转录指南。开发者在实际接入过程中，若需优化连接稳定性或获取更多资源，可通过API中转站获取支持。

网络标签：

相关问题