实时 API 开发者说明

我们最近宣布了我们最新的语音转语音模型 gpt-realtime，此外还有 Realtime API 的全面可用以及一系列新的 API 功能。Realtime API 和语音转语音 (s2s) 模型已正式全面可用 (GA)，在模型质量、可靠性和开发者体验方面都有重大改进。

你可以在文档和API 参考中了解新的 API 功能，但我们想重点介绍一些你可能错过的功能，并提供关于何时使用它们的指导。如果你正在集成 Realtime API，我们希望你会觉得这些笔记有趣。

模型改进

新模型包含多项改进，旨在更好地支持生产环境中的语音应用。本文重点介绍 API 变更。为了更好地理解和使用该模型，我们推荐发布公告博客文章和实时提示指南。不过，我们会指出一些具体细节。

关于使用此模型的几点关键建议：

• 在实时演练场中尝试提示词。
• 使用 marin 或 cedar 语音以获得最佳助手语音质量。
• 为新模型重写提示词。由于指令遵循能力的改进，具体的指令现在强大得多。
  • 例如，一个说“当 Y 时总是说 X”的提示词，旧模型可能将其视为模糊的指导，而新模型可能会在意外情况下遵守它。
  • 注意你提供的具体指令。假设指令会被遵循。

API 形状变更

我们在 GA 发布时更新了 Realtime API 形状，这意味着现在有一个 beta 接口和一个 GA 接口。我们建议客户端迁移到基于 GA 接口进行集成，因为它提供了新功能，而 beta 接口最终将被弃用。

迁移所需的完整变更列表可以在beta 到 GA 迁移文档中找到。

你可以通过 beta 接口访问新的 gpt-realtime 模型，但某些功能可能不受支持。详见下文。

功能可用性

Realtime API GA 版本包含许多新功能。其中一些在旧模型上启用，另一些则没有。

*由于 beta 模型缺少异步函数调用，没有输出的待处理 MCP 工具调用可能无法被模型妥善处理。我们建议将 GA 模型与 MCP 配合使用。

温度变更

GA 接口已移除 temperature 作为模型参数，而 beta 接口将 temperature 限制在 0.6 - 1.2 范围内，默认值为 0.8。

你可能会问：“为什么用户不能任意设置温度，并将其用于使响应更加确定性等用途？”答案是，温度在该模型架构中的表现不同，用户几乎总是通过将温度设置为推荐的 0.8 获得最佳效果。

据我们观察，无法通过低温度使这些音频响应具有确定性，而较高的温度会导致音频异常。我们建议通过提示词实验来控制模型行为的这些维度。

新功能

除了从 beta 到 GA 的变更之外，我们还为 Realtime API 增加了几项新功能。

所有功能均在 文档 和 API 参考 中介绍，但在此我们将重点介绍在集成和迁移过程中如何思考新功能。

会话空闲超时

对于某些应用，用户长时间没有输入会出乎意料。想象一下一通电话——如果我们听不到对方的声音，我们会询问他们的状况。也许模型没有听清用户说了什么，或者用户不确定模型是否还在说话。我们添加了一项功能，可以自动触发模型说类似这样的话：“你还在吗？”

通过在轮次检测的 server_vad 设置上设置 idle_timeout_ms 来启用此功能。 超时值将在模型最后一次响应的音频播放完毕后应用—— 即超时值设置为 response.done 时间加上音频播放时长再加上超时时间。如果在该时段内 VAD 未触发，则触发超时。

当超时被触发时，服务器会发送一个 input_audio_buffer.timeout_triggered 事件，该事件随后将空音频段提交到对话历史中并触发模型响应。 提交空音频让模型有机会检查 VAD 是否失败，以及在相关时段内是否存在用户发言。

客户端可以这样启用此功能：

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "instructions": "You are a helpful assistant.",
    "audio": {
      "input": {
        "turn_detection": {
          "type": "server_vad",
          "idle_timeout_ms": 6000
        }
      }
    }
  }
}

长对话与上下文处理

我们调整了 Realtime API 处理长会话的方式。需要注意以下几点：

• 实时会话现在最长可持续 60 分钟，此前为 30 分钟。
• gpt-realtime 模型的令牌窗口为 32,768 个令牌。响应最多可消耗 4,096 个令牌。这意味着模型的最大输入为 28,672 个令牌。
• 会话指令加工具的最大长度为 16,384 个令牌。
• 当会话达到 28,672 个令牌时，服务将自动截断（丢弃）消息，但此设置可配置。
• GA 服务会在有转录文本可用时自动丢弃部分音频令牌以节省令牌。

配置截断设置

当对话上下文窗口填满至令牌限制时，达到限制后，Realtime API 会自动开始从会话开头（最早的消息）截断（丢弃）消息。 你可以通过设置 "truncation": "disabled" 来禁用此截断行为，该设置会在响应的输入令牌过多时抛出错误。不过，截断很有用，因为即使输入大小对模型来说过大，会话仍会继续。Realtime API 不会对丢弃的消息进行摘要或压缩，但你可以自行实现。

截断的一个负面影响是，修改对话开头的消息会破坏 token 提示缓存。提示缓存的工作原理是识别提示词前缀中完全相同的精确匹配内容。在随后的每一轮中，只有未发生变化的 token 才会被缓存。当截断改变了对话的开头时，可缓存的 token 数量就会减少。

我们已实施一项功能来缓解这一负面影响：每当发生截断时，会截断超出必要量的内容。将保留比例设置为 0.8，即可截断 20% 的上下文窗口，而不是仅截断到刚好使输入 token 数量低于上限。其思路是一次性截断更多上下文窗口，而不是每次都截断一点点，从而减少破坏缓存的频率。这种对缓存友好的方法可以为达到输入限制的长会话降低成本。

{
  "type": "session.update",
  "session": {
    "truncation": {
      "type": "retention_ratio",
      "retention_ratio": 0.8
    }
  }
}

异步函数调用

Responses API 会在函数调用后立即强制返回函数响应，而 Realtime API 则允许客户端在函数调用挂起时继续会话。这种延续性对用户体验有益，能让实时对话自然地继续进行，但模型有时会幻觉出并不存在的函数响应内容。

为缓解这一问题，GA 版 Responses API 增加了占位响应，其内容经过我们在实验中的评估和调优，以确保即使在等待函数响应时，模型也能优雅地运行。如果你向模型询问函数调用的结果，它会说类似“我还在等那个结果”的话。此功能对新模型自动启用——你这边无需做任何更改。

EU 数据驻留

现在已专门针对 gpt-realtime-2025-08-28 和 gpt-4o-realtime-preview-2025-06-03 支持 EU 数据驻留。必须为组织明确启用数据驻留，并通过 https://eu.api.openai.com 访问。

追踪

Realtime API 会将追踪日志记录到 开发者控制台，记录实时会话期间的关键事件，有助于调查和调试。作为 GA 的一部分，我们推出了几种新的事件类型：

• 会话已更新（当 session.updated 事件发送给客户端时）
• 输出文本生成（用于模型生成的文本）

托管提示词

你现在可以将 提示词与 Realtime API 配合使用，这是一种便捷的方式，让应用代码引用可以单独编辑的提示词。提示词包括指令和会话配置，例如轮次检测设置。

你可以在 实时演练场中创建提示词，根据需要进行迭代和版本管理，然后客户端可以通过 ID 引用该提示词，如下所示：

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {
      "id": "pmpt_123", // your stored prompt ID
      "version": "89", // optional: pin a specific version
      "variables": {
        "city": "Paris" // example variable used by your prompt
      }
    },
    // You can still set direct session fields; these override prompt fields if they overlap:
    "instructions": "Speak clearly and briefly. Confirm understanding before taking actions."
  }
}

如果提示词设置与传递给会话的其他配置重叠，如上面的示例所示，则会话配置优先，因此客户端既可以使用提示词的配置，也可以在会话时对其进行操作。

边带连接

Realtime API 允许客户端通过 WebRTC 或 SIP 直接连接到 API 服务器。不过，你很可能希望将工具调用和其他业务逻辑保留在应用服务器上，以保持这些逻辑的私密性并与客户端无关。

通过边带控制通道连接，可以将工具调用、业务逻辑和其他细节安全地保留在服务器端。我们现在为 SIP 和 WebRTC 连接都提供了边带选项。

边带连接意味着同一实时会话存在两个活动连接：一个来自用户的客户端，另一个来自你的应用服务器。服务器连接可用于监控会话、更新指令以及响应工具调用。

有关更多信息，请参阅边带连接文档。

开始构建

我们希望这是一种有助于你了解正式可用的 Realtime API 和新实时模型有何变化的方式。

既然你已经了解了更新后的框架，查看实时文档以构建语音代理、启动连接或开始提示实时模型。