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生成），流程如下：

浏览器向开发者控制的服务器请求生成临时API密钥；
开发者服务器使用标准API密钥通过OpenAI REST API请求临时密钥，并返回给浏览器（注：临时密钥当前有效期为1分钟）；
浏览器使用临时密钥通过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-client

import os
import json
import websocket

OPENAI_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 os
import json
import websocket

OPENAI_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中转站获取支持。

posted @ 2025-08-07 13:08 大A就是我阅读(130) 评论(0) 收藏举报

刷新页面返回顶部

damoxing

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

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

Realtime API 核心能力

快速上手 Realtime API

示例应用参考

合作伙伴集成方案

核心应用场景

1. 实时语音到语音对话

2. 实时转录

通过 WebRTC 连接 Realtime API

适用场景与优势

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

连接配置详情

WebRTC 初始化示例代码

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

事件发送与接收

通过 WebSockets 连接 Realtime API

适用场景与优势

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

WebSocket 初始化示例代码

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

转录场景 WebSocket 初始化示例代码

事件发送与接收

公告