OpenAI Realtime API

什么是 OpenAI Realtime API？

The OpenAI Realtime API 是一种专门设计的接口，旨在实现与 OpenAI 模型进行极低延迟的通信。它的主要优势在于处理连续的双向数据流，非常适合交互式、时间敏感的应用。此 API 原生支持复杂的多模态交互，允许开发人员集成语音到语音功能，处理音频、图像和文本的组合输入，并以近乎实时的方式生成音频或文本输出。

此功能为构建复杂的、响应迅速的应用打开了大门，例如直接在浏览器中构建先进的语音代理或集成实时音频转录服务。通过专注于速度和连续数据流，Realtime API 超越了传统的请求/响应模型，为真正具有对话性和沉浸感的 AI 体验奠定了基础。

核心特性

• 低延迟通信： 针对最小延迟进行了优化，这对自然流畅的语音交互和即时反馈循环至关重要。
• 多模态支持： 接受包括音频、图像和文本在内的输入，并生成音频和文本输出。
• 语音到语音原生支持： 专为构建流畅的语音代理而设计，其中音频输入会立即转换为音频输出。
• 灵活的连接方法： 支持三种主要接口以适应不同的部署环境：
  • WebRTC： 理想情况下用于浏览器内直接的客户端交互。
  • WebSocket： 最适合需要一致、低延迟连接的服务器端应用程序。
  • SIP： 专为与传统 VoIP 电信系统集成而设计。
• 实时音频转录： 能够在通过 WebSocket 连接到达时转录音频流。
• 服务器端控制： 允许开发人员管理会话生命周期、实施护栏以及从服务器调用外部工具。
• 简化的身份验证： 使用通过专用 REST 端点（/v1/realtime/client_secrets）生成的临时 API 密钥进行安全的客户端初始化。

如何使用 OpenAI Realtime API

开始使用 Realtime API 通常涉及利用 Agents SDK for TypeScript，这是构建基于浏览器的语音代理最快途径。总体工作流程涉及建立连接、管理会话，然后与模型进行交互。

1. 初始化： 使用 SDK 定义您的代理参数（如名称和指令），或准备直接连接。
2. 连接设置： 选择您的连接方法（浏览器使用 WebRTC，服务器使用 WebSocket）。对于 WebRTC，您通常会使用从 REST 端点获取的临时密钥来初始化 RealtimeSession。
3. 会话连接： 调用 session.connect() 以自动链接麦克风和音频输出（对于语音代理）或建立数据流。
4. 交互： 连接后，利用提供的指南进行提示、管理对话事件或实施服务器端逻辑（如工具调用）来引导模型的行为。

对于不使用 Agents SDK 的直接集成，开发人员必须查阅 WebRTC、WebSocket 或 SIP 连接的特定指南，以处理会话初始化和数据交换（例如，WebRTC 的 SDP 协商）。

使用场景

1. 交互式语音助手： 构建复杂的、听起来自然的对话代理，可直接通过网络浏览器或移动应用访问，提供即时语音响应而没有明显的延迟。
2. 实时客户支持机器人： 部署可以通过 SIP 集成处理实时语音呼叫的 AI 代理，通过电话提供即时分诊、信息检索或复杂的交易处理。
3. 多模态数据处理： 创建应用程序，分析实时视频流（使用图像输入）并结合语音命令（音频输入）来执行复杂任务，例如指导用户完成物理维修过程。
4. 实时会议转录和摘要： 利用 WebSocket 连接对会议期间的音频进行实时转录，从而可以立即进行索引、关键字标记或即时摘要生成。
5. 低延迟游戏 NPC： 将 AI 角色集成到实时交互环境中，其中玩家的语音命令必须立即得到游戏角色的上下文感知语音响应。

常见问题 (FAQ)

问：Realtime API 与标准 REST API 调用有什么主要区别？ 答：标准 REST API 针对离散的请求/响应操作进行了优化。Realtime API 专为连续的双向流式通信而构建，优先考虑交互式语音和实时数据交换所需的极低延迟。

问：我可以直接在移动应用程序中使用 Realtime API 吗？ 答：可以。虽然 Agents SDK 侧重于通过 WebRTC 进行浏览器使用，但底层的 Realtime API 支持 WebSocket 连接，在您的后端服务器安全获取必要的临时客户端密钥后，可以在原生移动环境中实现这些连接。

问：如何处理客户端 WebRTC 连接的身份验证？ 答：您必须首先使用您的主 API 密钥调用服务器端 REST 端点（POST /v1/realtime/client_secrets）。这将返回一个临时令牌（ek_...），客户端随后安全地使用该令牌来初始化 WebRTC 或 WebSocket 会话。

问：OpenAI-Beta: realtime=v1 标头发生了什么变化？ 答：仅当您有意保留旧版 Realtime Beta 接口的行为时，才需要此标头。对于使用正式发布 (GA) 接口的新集成，应从 REST API 请求和 WebSocket 连接中删除此标头。

问：对于 Web 应用程序，哪种连接方法能提供最低延迟？ 答：对于直接的浏览器交互，WebRTC 通常是 Realtime API 推荐和最优化的一种连接方法，可实现客户端与模型之间尽可能低的延迟。