Realtime API 开发者笔记

我们最近宣布推出了最新的语音到语音 模型 gpt-realtime，同时宣布 Realtime API 正式发布，并 推出了一系列新的 API 功能。Realtime API 和语音到语音（s2s）模型已正式发布（GA），在模型质量、可靠性和开发体验方面均有显著提升。

您可以在 文档和 API 参考中了解新的 API 功能。这里，我们想重点介绍几个您可能忽略的功能，并说明它们适合在什么情况下使用。 如果您正在集成 Realtime API，希望这些笔记能给您带来启发。

模型改进

新模型包含多项改进，旨在更好地支持生产环境中的语音应用。 本文重点介绍 API 的变化。要更好地理解和使用该模型，我们建议您阅读发布博文和 实时交互提示词指南。不过，我们也会在这里介绍一些具体要点。

使用该模型时，有几条重要建议：

• 在实时 Playground中尝试不同的提示。
• 使用 marin 或 cedar 音色，以获得最佳的助手语音质量。
• 针对新模型重新编写提示。由于指令遵循能力有所提升，具体指令现在能发挥更大的作用。
  • 例如，对于“只要出现 Y，就始终说 X”这样的提示，旧模型可能只是将其视为宽泛的指导，而新模型可能会在您意想不到的情况下也遵循这条指令。
  • 请留意您提供的具体指令，并以模型会遵循这些指令为前提来编写。

API 接口结构变化

随着正式发布，我们更新了 Realtime API 的接口结构，因此现在有 beta 接口和 GA 接口。我们建议客户端迁移到 GA 接口，因为它提供了新功能，而 beta 接口最终将被弃用。

迁移所需的完整变更列表，请参阅从 beta 迁移到 GA 的文档。

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

功能可用性

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

*由于 beta 模型不支持异步函数调用，它可能无法妥善处理尚未完成且没有输出的 MCP 工具调用。我们建议将 GA 模型与 MCP 配合使用。

温度参数的变化

GA 接口已移除模型参数 temperature，而 beta 接口将 温度限制在 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 处理长会话的方式。以下几点需要注意：

• 实时会话的最长时长现已从 30 分钟延长至 60 分钟。
• gpt-realtime 模型的 Token 窗口为 32,768 个 Token。响应最多可使用 4,096 个 Token。这意味着模型最多可接收 28,672 个输入 Token。
• 会话指令与工具的总长度最多为 16,384 个 Token。
• 当会话达到 28,672 个 Token 时，服务会自动截断（丢弃）消息，但这一行为可以配置。
• 正式版服务会在有转录文本时自动丢弃部分音频 Token，以节省 Token。

配置截断设置

当对话上下文窗口达到 Token 上限后，Realtime API 会自动从会话开头截断（丢弃）消息，也就是移除最早的消息。 您可以设置 "truncation": "disabled" 来禁用这一截断行为，这样在生成响应所需的输入 Token 过多时， API 就会抛出错误。不过，截断也有其用处：即使输入大小超出模型的容量，会话仍能继续。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 允许客户端在函数调用尚未完成时继续会话。这样可以让实时对话自然地继续，改善用户体验，但模型有时会产生幻觉，编造尚不存在的函数响应内容。

为缓解这一问题，正式版 Responses API 增加了占位响应。我们通过实验评估并调整了这些响应的内容，确保模型在等待函数响应时也能妥善应对。如果您询问模型某个函数调用的结果，它会给出类似“我还在等待结果”的回答。新模型会自动启用此功能，您无需做任何更改。

欧盟数据驻留

目前，欧盟数据驻留已专门支持 gpt-realtime-2025-08-28 和 gpt-4o-realtime-preview-2025-06-03。必须为组织显式启用数据驻留，并通过 https://eu.api.openai.com 访问。

追踪

Realtime API 会将追踪记录写入开发者控制台，记录实时会话期间的关键事件，有助于排查问题和调试。随着正式版发布，我们推出了几种新的事件类型：

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

托管提示

您现在可以在 Realtime API 中使用提示，让应用代码便捷地 引用可单独编辑的提示。提示既包含指令，也包含 会话配置，例如轮次检测设置。

您可以在实时 Playground 中创建提示，根据需要进行迭代和版本管理，然后客户端就能通过 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 和新实时模型带来的变化。

了解这些更新后，您可以查看实时 API 文档，构建语音智能体、建立连接，或开始为实时模型编写提示。