OpenAI 发布 Realtime API GA 版与 gpt-realtime 模型开发者说明

我们最近宣布了最新的语音到语音模型 gpt-realtime，同时 Realtime API 正式可用，并推出了一系列新的 API 功能。Realtime API 和语音到语音（s2s）模型已进入正式可用（GA）阶段，在模型质量、可靠性和开发者体验方面都有重大改进。

你可以在文档和 API 参考中了解这些新的 API 功能，但我们想重点介绍几个你可能错过的功能，并就何时使用它们提供指导。 如果你正在集成 Realtime API，希望这些说明对你有帮助。

模型改进

新模型包含多项改进，旨在更好地支持生产级语音应用。本文重点讨论 API 变更。要更好地理解和使用该模型，我们推荐阅读发布博客文章和 实时提示指南。不过，我们会指出一些具体要点。

使用该模型的几条关键建议：

• 在实时演练场中尝试提示。
• 使用 marin 或 cedar 语音以获得最佳的助手语音质量。
• Rewrite prompts for the new model. Due to instruction-following improvements, specific instructions are now much more powerful.
  • 例如，一条写着“当 Y 时总是说 X”的提示，旧模型可能将其视为模糊的指导，而新模型可能会在意想不到的情况下遵循它。
  • 注意你提供的具体指令。假设指令会被遵循。

API 形态变更

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

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

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

功能可用性

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

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

温度变更

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

你可能会问：“为什么用户不能任意设置 temperature，并用它来让响应更具确定性？”答案是，对于这种模型架构，temperature 的行为有所不同，用户几乎总是最好将 temperature 设置为推荐的 0.8。

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

新功能

除了从 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 处理长会话的方式。有几点需要注意：

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

配置截断设置

当对话上下文窗口填满达到 token 限制时，达到限制后，Realtime API 会自动开始从会话开头（最旧的消息）截断（丢弃）消息。 你可以通过设置 "truncation": "disabled" 来禁用此截断行为，这样当响应输入 token 过多时会抛出错误。 然而，截断很有用，因为即使输入大小增长到超出模型处理能力，会话也能继续。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 增加了占位响应，其内容经过我们在实验中的评估和调优，以确保模型即使在等待函数响应时也能表现优雅。如果你向模型询问函数调用的结果，它会说类似“我还在等那个结果”的话。此功能对新模型自动启用——你无需做任何更改。

欧盟数据驻留

欧盟数据驻留现已专门支持 gpt-realtime-2025-08-28 和 gpt-4o-realtime-preview-2025-06-03。数据驻留必须为组织显式启用，并通过 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 和新实时模型有哪些变化。

现在你已了解更新后的框架，请参阅实时文档来构建语音代理、启动连接，或开始对实时模型进行提示。