OpenAI Realtime API 是什麼：語音到語音會話、WebRTC 與 WebSocket、臨時密鑰和事件機制

本文根據 OpenAI 官方《Getting started with the Realtime API》和《Realtime conversations》整理，資料核對於 2026-11-05。配圖為本站整理的示意圖，不是介面截圖。代碼裏的模型名取自官方當天示例，請以官方模型頁為準。本站（bigolab.com）不是 OpenAI 官方網站。API 是按用量計費的獨立服務，與 ChatGPT 訂閱分開計算，Key 的獲取見 /guides/openai-api-key。

適用於誰

• 聽說過 Realtime API，但搞不清它和普通的 Responses 請求、語音轉寫有什麼區別的人；
• 想做語音助手、電話機器人、可以隨時打斷的對話介面的開發者；
• 讀到官方說文字轉語音接口要棄用、想知道“官方推薦的方向”長什麼樣的人。

結論先說

1. Realtime API 是做“語音到語音”對話的接口：官方說，模型直接處理音頻，保持對話狀態，還能調用工具。
2. 適合“像聊天一樣即時”的交互：官方點名的特性是可以打斷（barge-in）、首個音頻延遲低、自然輪流發言、實時工具調用。
3. 它是有狀態的會話（session），通過事件通信，不是“一次請求一次響應”的寫法。
4. 瀏覽器裏用 WebRTC，伺服器裏用 WebSocket，瀏覽器不能拿長期密鑰，要由你的伺服器簽發臨時密鑰。
5. 一次會話最長 60 分鐘。
6. 不需要對話、只想把聲音變成文字，用轉寫模式或文件轉寫，不用這套。

圖：本站根據 OpenAI 官方《Getting started with the Realtime API》 整理的示意圖

一、和普通請求有什麼不同

之前的文章裏，無論是 /guides/openai-responses-api 還是流式輸出，都是“你發一個請求，模型回一個響應”。Realtime 不一樣，官方把它描述成一個有狀態的會話，有三個組成部分：

• Session（會話對象）：控制交互的參數，比如用哪個模型、哪種聲音、其他配置；
• Conversation（對話）：當前會話裏的用戶輸入項和模型輸出項；
• Response（響應）：模型生成的音頻或文字項，加入對話。

你用客戶端事件去改變會話狀態，用服務端事件去響應狀態的變化。如果用 WebRTC，大部分音頻採集和播放可以由瀏覽器的 WebRTC 接口代勞；如果用 WebSocket 傳音頻，你需要手動處理輸入音頻緩衝區，把 Base64 編碼的音頻放進 JSON 事件裏發給伺服器。

二、官方的瀏覽器接入流程

官方入門頁用 Agents SDK 的 JavaScript 版演示。四步：

1. 你的應用伺服器為這次 Realtime 會話創建一個臨時客戶端密鑰（ephemeral client secret）；
2. 前端創建 RealtimeSession；
3. 會話在瀏覽器裏通過 WebRTC 連接，在伺服器上通過 WebSocket 連接；
4. 代理在這個會話內處理音頻輪次、工具、打斷和交接。

官方示例：

javascript
import { RealtimeAgent, RealtimeSession } from "@openai/agents/realtime";

const agent = new RealtimeAgent({
  name: "Assistant",
  instructions: "You are a helpful voice assistant.",
});

const session = new RealtimeSession(agent, {
  model: "gpt-realtime-2.1", // 以官方模型頁當天為準
});

await session.connect({
  apiKey: "ek_...(來自你伺服器的臨時密鑰)",
});

要點：apiKey 填的是你伺服器簽發的臨時密鑰，不是你的 OpenAI 長期 Key。 長期 Key 的保管見 /guides/openai-api-key，絕不能寫進網頁。官方建議把傳輸細節放在 session 層，把業務邏輯放在代理定義裏，工具、交接和護欄的加法和文本代理一樣。如果需要更底層的控制，官方有 WebRTC 和 WebSocket 的專門連接指南，本文不展開。

三、事件和 session.update

會話建立後，伺服器會先發一個 session.created 事件，說明會話準備好了。之後你可以用 session.update 事件修改配置，伺服器回 session.updated，裏面是新的狀態。官方說明：

• 大多數屬性可以隨時更新，唯一的例外是 voice：模型在會話裏輸出過一次音頻之後，就不能再改聲音了；
• 在 session.update 裏，官方示例設定了 output_modalities（["audio"] 或 ["text"]，Python 示例註釋裏寫明二選一、不要組合）、輸入輸出音頻格式、turn_detection（如 semantic_vad）、instructions 等；
• 出現錯誤時，伺服器會發 error 事件。和 HTTP 不同，這裏沒有天然的一問一答，所以客戶端事件要帶上 event_id，出錯時伺服器返回的錯誤裏會帶回同一個 event_id，你才知道是哪個事件出了問題。

官方當前可用的聲音：alloy、ash、ballad、coral、echo、sage、shimmer、verse、marin、cedar，推薦 marin 或 cedar。

四、它和別的音頻接口怎麼分工

圖：本站根據 OpenAI 官方《Getting started with the Realtime API》 整理的示意圖

官方入門頁末尾給出了其他音頻工作流的去向：

• 連續翻譯：用 Live translation；
• 實時字幕：用 Live transcription，也就是 Realtime 的轉寫模式；
• 錄好的音頻轉寫：用 File transcription，寫法見 /guides/openai-api-speech-to-text-text-to-speech。

官方在《Realtime conversations》裏也說：如果你不需要和模型對話，也就是不指望得到回應，可以用轉寫模式。

和文字轉語音的關係：官方 Text to speech 頁說，tts-1、tts-1-hd、gpt-4o-mini-tts 已棄用，將在 2027 年 1 月 6 日停止服務，遷移方向是 Realtime API 裏的 gpt-realtime-2.1-mini，並強調這是工作流的變化，不是改個模型名。也就是說，要做語音輸出的新項目，需要把思路換成 Realtime 會話。

五、官方的幾個提醒

安全標識。 應用如果能識別個人用戶，官方推薦（不強制）在 Realtime 請求裏帶 OpenAI-Safety-Identifier 請求頭，用穩定、保護私隱的值，例如內部用戶 ID 的哈希。使用臨時令牌時，要在你伺服器上創建客戶端密鑰的那個請求裏設定這個頭。官方強調這個標識不會從 Responses 請求沿用，每次創建或連接 Realtime 會話都要傳。

從 Beta 遷移到 GA。 如果你手上還有 Beta 版 Realtime 集成，官方要求先遷移到 GA 再做新工作。主要變化：去掉 OpenAI-Beta: realtime=v1 請求頭；用 POST /v1/realtime/client_secrets 為瀏覽器或手機客戶端創建臨時憑據；WebRTC 用 /v1/realtime/calls；會話和事件的結構也有調整，比如要設定 session.type、輸出音頻配置放到 session.audio.output 下、使用 response.output_text.delta、response.output_audio.delta 之類的新事件名。

成本。 Realtime 的計費方式（包括緩存）官方有專門的 Cost optimization 頁面，價格以官方價格頁當天為準，見 /guides/openai-api-price-official-table。

常見問題

Q：Realtime 只能做語音嗎？

不是。官方《Realtime conversations》講了文字輸入輸出、圖片輸入和函數調用，會話裏可以只要文字輸出，也可以只要音頻輸出。

Q：我的伺服器上能直接連嗎？

可以，官方說伺服器用 WebSocket；瀏覽器用 WebRTC。兩種方式在官方都有專門指南。

Q：連接被限流或報錯？

通用的限速處理見 /guides/openai-api-429-error，限額與層級見 /guides/openai-api-usage-tiers-rate-limits。

參考資料

• OpenAI 官方：Getting started with the Realtime API — https://developers.openai.com/api/docs/guides/realtime
• OpenAI 官方：Realtime conversations — https://developers.openai.com/api/docs/guides/realtime-conversations