Realtime API 開發者筆記

我們最近宣布推出最新的語音到語音 模型 gpt-realtime，同時宣布 Realtime API 正式推出，並 新增多項 API 功能。Realtime API 和語音到語音（s2s）模型已正式推出（GA），在模型品質、可靠性和開發便利性方面都有大幅改善。

你可以在 文件和 API 參考文件中了解 API 的新功能，而我們想在這裡介紹幾項你可能忽略的功能，並說明適合使用這些功能的時機。 如果你正在整合 Realtime API，希望這些筆記能讓你有所收穫。

模型改進

新模型包含多項改進，旨在更完善地支援正式環境中的語音應用程式。 本文著重介紹 API 的變更。若想更深入了解並運用這個模型，建議閱讀發布公告文章和 即時互動提示詞指南。不過，我們也會在這裡說明幾個具體重點。

使用這個模型時，有幾項重要建議：

• 在即時 Playground 中嘗試不同的提示詞。
• 使用 marin 或 cedar 聲音，以獲得最佳的助理語音品質。
• 針對新模型重新撰寫提示詞。由於遵循指示的能力有所提升，具體指示現在能發揮更大的作用。
  • 舉例來說，「只要發生 Y，就一定要說 X」這樣的提示詞，舊模型可能只會視為概略的指引，而新模型卻可能在你意想不到的情境下也照做。
  • 請留意你提供的具體指示，並以模型會確實遵循這些指示為前提來撰寫。

API 介面變更

隨著 GA 版本推出，我們也更新了 Realtime API 的介面，因此目前有 beta 介面和 GA 介面。我們建議用戶端遷移至 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 過多時 拋出錯誤。不過，截斷的好處在於，即使輸入量超過模型能處理的範圍，工作階段仍可繼續。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 文件，開始打造語音智慧體、建立連線，或為即時模型撰寫提示詞。