Realtime 即時語音

WSS wss://test.kailin.com.cn/v1/realtime

基於 WebSocket 的即時雙向語音對話（OpenAI Realtime 協定），適合語音助理、即時翻譯等低延遲情境。

連線

模型名稱透過查詢字串傳遞，驗證方式與其他 HTTP 端點相同：

wss://test.kailin.com.cn/v1/realtime?model=gpt-4o-realtime-preview

const ws = new WebSocket(
  'wss://test.kailin.com.cn/v1/realtime?model=gpt-4o-realtime-preview',
  {
    headers: {
      Authorization: 'Bearer sk-your-token',
      'OpenAI-Beta': 'realtime=v1',
    },
  }
);

備註

瀏覽器端的 new WebSocket 無法自訂請求標頭。可改以子協定參數傳遞權杖，或由你自己的後端代理 WebSocket 連線（建議做法，可避免權杖暴露在前端）。

訊息格式

所有訊息都是帶有 type 欄位的 JSON 文字框架。

建立工作階段

連線成功後伺服器會推送 session.created，用戶端通常會先傳送 session.update 來設定語音與回合偵測：

{
  "type": "session.update",
  "session": {
    "instructions": "You are a voice assistant. Keep answers short.",
    "voice": "alloy",
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_transcription": { "model": "whisper-1" },
    "turn_detection": { "type": "server_vad" }
  }
}

傳送使用者音訊

音訊以 Base64 編碼的 PCM16（24kHz 單聲道）分塊傳送：

{ "type": "input_audio_buffer.append", "audio": "<base64 pcm16>" }

{ "type": "input_audio_buffer.commit" }

啟用 server_vad 後，伺服器會自動偵測說話結束並提交，無需手動 commit。

觸發回應

{
  "type": "response.create",
  "response": { "modalities": ["text", "audio"], "instructions": "Be enthusiastic." }
}

伺服器事件

事件	說明
session.created / session.updated	工作階段建立 / 設定生效
input_audio_buffer.speech_started / _stopped	VAD 偵測到說話開始 / 結束
input_audio_buffer.committed	音訊緩衝已提交
conversation.item.created	對話項目已建立
response.audio_transcript.delta / _done	回覆文字轉寫的增量 / 完成
response.audio.delta / _done	回覆音訊增量（Base64 PCM16）
response.text.delta / _done	純文字回覆增量
response.done	本輪回覆結束
error	錯誤事件

完整流程範例

const ws = new WebSocket(url);

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'session.update',
    session: { voice: 'alloy', turn_detection: { type: 'server_vad' } },
  }));
  // send an audio chunk…
  ws.send(JSON.stringify({
    type: 'input_audio_buffer.append',
    audio: btoa(String.fromCharCode(...pcmChunk)),
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case 'response.audio.delta':
      playPcmChunk(atob(msg.delta));
      break;
    case 'response.audio_transcript.delta':
      appendSubtitle(msg.delta);
      break;
    case 'response.done':
      console.log('turn finished', msg.response.usage);
      break;
  }
};

警告

Realtime 端點依音訊時長計費，費用明顯高於文字端點，測試時請留意工作階段長度。是否可用取決於渠道設定的模型。