如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題
Sep 12, 2025 Audio

Realtime API 開發者筆記

近期即時語音到語音功能更新中值得留意的細節

作者: Peter Bakkum

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 ✅ 搭配非同步函式呼叫效果最佳 ✅ 缺少非同步函式呼叫時功能受限*
音訊 Token → 文字 ✅ ❌
歐盟資料駐留 ✅ ✅ 僅限 06-03 版本
SIP ✅ ✅
閒置逾時 ✅ ✅

*由於 Beta 模型不支援非同步函式呼叫,如果 MCP 工具呼叫尚未完成,也還沒有輸出,模型可能無法妥善處理。建議搭配 GA 模型使用 MCP。

溫度參數的變更

GA 介面已移除 temperature 模型參數。Beta 介面的溫度範圍則限制在 0.6 - 1.2,預設值為 0.8。

你可能會問:「為什麼不能自由設定溫度,例如讓相同輸入更容易得到相同的回應?」這是因為在這種模型架構下,溫度對輸出的影響有所不同。幾乎在所有情況下,使用建議值 0.8 都能得到最佳效果。

根據我們的觀察,即使降低溫度,也無法讓模型每次都產生相同的音訊回應,而較高的溫度則會導致聲音異常。建議試著調整提示詞,藉此控制模型在這些方面的表現。

新功能

除了從 Beta 到 GA 的變更,我們也為 Realtime API 新增了幾項功能。

開發文件和 API 參考文件涵蓋所有功能。這裡著重說明在整合或遷移時,可以如何運用這些新功能。

對話閒置逾時

在某些應用程式中,使用者長時間沒有輸入並不尋常。想像一下,通電話時如果一直聽不到對方的聲音,我們通常會開口確認對方是否還在線上。模型可能沒聽到使用者說的話,也可能是使用者不確定模型是否說完了。我們新增了一項功能,可以自動讓模型問一句:「你還在嗎?」

若要啟用這項功能,請設定 idle_timeout_ms,這個欄位位於對話輪次偵測的 server_vad 設定中。逾時會從模型上一則回應的音訊播放完畢後開始計算。也就是說,觸發逾時的時間點是 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 模型的上下文視窗可容納 32,768 個 Token。每次回應最多可使用 4,096 個 Token,因此模型的輸入上限為 28,672 個 Token。
  • 工作階段指示與工具定義的總長度上限為 16,384 個 Token。
  • 工作階段達到 28,672 個 Token 時,服務會自動截斷上下文(捨棄訊息)。你可以調整這項設定。
  • 有逐字稿可用時,GA 服務會自動捨棄部分音訊 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 允許用戶端在函式呼叫尚未完成時繼續工作階段。這讓即時對話能自然進行,改善使用者體驗,但模型有時會憑空編造尚未收到的函式回應內容。

為了減輕這個問題,GA 版 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 正式版和新一代即時模型有哪些變更。

瞭解這些更新後,你可以參閱 Realtime API 文件,開始建構語音智慧體、建立連線,或試著用提示詞引導即時模型。