TRAE-AI编程
OpenAI Realtime API 入门
使用 Realtime API 构建语音到语音智能体。模型直接处理音频、维护对话状态，并可调用工具。本指南从浏览器应用中的 Agents SDK 入手；需要直接控制时，请使用较底层的连接指南。
如果需要全双工对话和独立的委派后端，请参阅 GPT-Live。语音架构与串联流水线的比较见语音智能体。
构建语音到语音智能体
当交互需要像对话一样即时、自然时，使用 Realtime API。对于需要用户插话打断、低首段音频延迟、自然轮次交替和实时工具使用的语音智能体，这是合适的起点。
典型浏览器流程如下：
- 应用服务器为 Realtime 会话创建临时客户端密钥。
- 前端创建
RealtimeSession。 - 会话在浏览器中通过 WebRTC 连接，或在服务器上通过 WebSocket 连接。
- 智能体在会话内处理音频轮次、工具、打断和任务移交。
启动实时语音会话：
来源示例 1（javascript）：
程序文字译释48：你是乐于助人的语音助手。
程序文字译释49：ek_...代表服务器签发的临时密钥占位符。
// [中文] 保留原例中客户端、输入和返回值的处理顺序；本段需结合所在小节的连接前提使用，未通过真实API调用验证。
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 请求头发送标识符。使用临时令牌时，在服务器创建客户端密钥的请求中设置该头，以便把标识符关联到会话。从可信服务器通过 WebSocket 或统一 WebRTC 接口连接时，在连接请求中设置该头。
安全标识符不会从 Responses API 请求或其他会话自动继承。如果应用其他部分使用 Responses API 的 safety_identifier 参数，应在每次创建或连接 Realtime 会话时传递同一个稳定值。
从 Beta 迁移到正式版
如果仍在使用 Realtime Beta 集成，应先迁移到正式版接口，再继续新增工作。主要变化包括：
- 调用正式版接口时，移除
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 会话参考与浏览器示例。
后续步骤
- 管理对话：配置会话，处理音频、文本与事件。
- 语音活动检测：配置自动轮次检测。
- 工具与 MCP：添加函数、MCP 服务器与连接器。
- 语音模型提示词：选择 Realtime 模型对应的指南。
- 成本优化：了解 Realtime 用量核算与缓存。
- 服务端控制：让工具执行与会话控制保留在服务器上。
更多建议：