如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

Realtime API 入门

使用 Realtime API 和 Agents SDK 构建在浏览器中运行的语音智能体。

使用 Realtime API 构建支持语音到语音交互的智能体。模型直接处理音频,维护对话状态,还可以调用工具。本指南首先介绍如何使用 Agents SDK 构建浏览器应用。如果您需要直接控制底层连接,请参阅相应的连接指南。

如果您需要将后端处理委托给独立服务来实现全双工对话,请参阅 GPT-Live。如需比较不同的语音架构和链式处理流程,请参阅语音智能体。

构建支持语音到语音交互的智能体

如果您希望交互像日常对话一样自然、即时,可以使用 Realtime API。如果您的语音智能体需要支持用户随时打断、以低延迟开始播放回复、自然地轮流发言以及实时调用工具,Realtime API 是最佳起点。

浏览器应用通常按以下步骤建立并使用会话:

  1. 应用服务器为 Realtime 会话创建临时客户端密钥。
  2. 前端创建一个 RealtimeSession。
  3. 会话在浏览器中通过 WebRTC 建立连接,在服务器上则通过 WebSocket 建立连接。
  4. 智能体在会话中处理各轮语音交互、工具调用、打断和智能体之间的任务交接。
启动实时语音会话
import { RealtimeAgent, RealtimeSession } from "@openai/agents/realtime";

const ephemeralKey = process.env.OPENAI_REALTIME_EPHEMERAL_KEY;
if (!ephemeralKey)
  throw new Error("Set OPENAI_REALTIME_EPHEMERAL_KEY from your server.");

const agent = new RealtimeAgent({
  name: "Assistant",
  instructions: "You are a helpful voice assistant.",
});

const session = new RealtimeSession(agent, {
  model: "gpt-realtime-2.1",
});

await session.connect({
  apiKey: ephemeralKey,
});

接下来,您可以像配置文本智能体一样,为 RealtimeAgent 添加工具、任务交接和防护机制。请在会话层处理音频传输,并在智能体定义中编写业务逻辑。

如果您需要控制底层传输,请先参阅以下文档:

安全标识符

如果您的应用能识别每位最终用户,请在 Realtime API 请求中附上安全标识符。OpenAI 建议使用安全标识符,但不作强制要求。安全标识符有助于 OpenAI 检测有害行为,并将处置措施限定于相关用户,避免影响整个组织。请选择一个稳定且能保护隐私的值,例如内部用户 ID 的哈希值。

对于 Realtime API 请求,请通过 OpenAI-Safety-Identifier 请求头发送标识符。如果使用临时 Token,请在服务器端创建客户端密钥的请求中设置此请求头,将标识符与会话关联。如果从受信任的服务器通过 WebSocket 或统一的 WebRTC 接口建立连接,请在连接请求中设置此请求头。

Realtime 会话不会自动沿用 Responses API 请求或其他会话中的安全标识符。如果您在应用的其他位置使用了 Responses API 的 safety_identifier 参数,请在创建或连接每个 Realtime 会话时传入同一个稳定值。

从测试版迁移到正式版(GA)

如果您的应用仍在使用测试版 Realtime 接口,请先将其迁移到正式版接口,再开展新的开发工作。主要变更如下:

  • 调用正式版接口时,移除 OpenAI-Beta: realtime=v1 请求头。
  • 使用 POST /v1/realtime/client_secrets 为浏览器或移动客户端创建临时凭据。
  • 建立 WebRTC 会话时,使用 /v1/realtime/calls。
  • 按正式版接口的要求更新会话和事件的数据结构。具体来说,请设置 session.type,将音频输出配置移至 session.audio.output 下,并使用新版响应事件名称,例如 response.output_text.delta、response.output_audio.delta 和 response.output_audio_transcript.delta。
  • 如果您要迁移语音到语音应用,请从浏览器示例入手。如果您要迁移转写工作流,请参阅实时转写。

有关当前正式版的使用流程,请参阅 Realtime 客户端事件参考、Realtime 会话参考和浏览器示例。

后续步骤

其他音频工作流

现在,您可以在音频与语音中选择合适的工作流并查阅通用音频术语。如需连续翻译,请参阅实时翻译。如需生成实时字幕,请参阅实时转写。如需转写已录制的音频,请参阅文件转写。