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

Realtime 對話

瞭解如何管理 Realtime 語音到語音對話。

透過 WebRTC 或 WebSocket 連上 Realtime API 後,即可呼叫 Realtime 模型(例如 gpt-realtime-2.1)進行語音到語音對話。你需要傳送用戶端事件來啟動操作,並監聽伺服器事件,以便在 Realtime API 執行操作時做出相應處理。

本指南說明使用模型功能時所需的事件流程,包括生成音訊與文字、圖片輸入及函式呼叫,也會介紹如何理解 Realtime 工作階段的狀態。

如果你不需要與模型對話,也就是不預期模型給予任何回應,可以使用 Realtime API 的轉錄模式。

Realtime 語音到語音工作階段

Realtime 工作階段是模型與已連線用戶端之間一段會保留狀態的互動。工作階段的主要組成部分如下:

  • 工作階段物件控制互動參數,包括使用哪個模型、產生音訊輸出時使用的聲音,以及其他設定。
  • 對話包含目前工作階段中的使用者輸入項目,以及模型產生的輸出項目。
  • 回應是模型產生的音訊或文字項目,會加入對話中。

輸入音訊緩衝區與 WebSocket

如果使用 WebRTC,WebRTC API 可協助處理與模型收發音訊時所需的大部分媒體操作。


如果使用 WebSocket 傳輸音訊,則需要手動操作輸入音訊緩衝區:將音訊以 Base64 編碼,再透過 JSON 事件傳送至伺服器。

這些部分共同構成 Realtime 工作階段。你可以使用用戶端事件更新工作階段的狀態,並監聽伺服器事件,以便在狀態變更時做出相應處理。

Realtime 工作階段狀態示意圖

工作階段生命週期事件

透過 WebRTC 或 WebSocket 啟動工作階段後,伺服器會傳送 session.created 事件,表示工作階段已就緒。在用戶端,你可以使用 session.update 事件更新目前工作階段的設定。大部分工作階段屬性都可以隨時更新,唯有模型輸出音訊時使用的 voice,在模型首次以音訊回應後,就無法在該工作階段中變更。Realtime 工作階段最長可持續 60 分鐘。

以下範例示範如何使用 session.update 用戶端事件更新工作階段。如需瞭解如何透過這些通道傳送用戶端事件,請參閱 WebRTC 或 WebSocket 指南。

更新模型在此工作階段中使用的系統指示
const event = {
  type: "session.update",
  session: {
    type: "realtime",
    model: "gpt-realtime-2.1",
    // Lock the output to audio (set to ["text"] if you want text without audio)
    output_modalities: ["audio"],
    audio: {
      input: {
        format: {
          type: "audio/pcm",
          rate: 24000,
        },
        turn_detection: {
          type: "semantic_vad",
        },
      },
      output: {
        format: {
          type: "audio/pcm",
          rate: 24000,
        },
        voice: "marin",
      },
    },
    // Use a server-stored prompt by ID. Optionally pin a version and pass variables.
    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.",
  },
};

// WebRTC data channel and WebSocket both have .send()
dataChannel.send(JSON.stringify(event));

工作階段更新後,伺服器會發出 session.updated 事件,其中包含工作階段的新狀態。

相關用戶端事件相關伺服器事件

session.update

session.created

session.updated

文字輸入與輸出

若要使用 Realtime 模型生成文字,可以將文字輸入加入目前的對話,要求模型生成回應,並監聽伺服器傳送的事件以掌握回應進度。若要生成文字,工作階段必須設定為支援 text 模態(預設已啟用)。

使用 conversation.item.create 用戶端事件建立新的文字對話項目。這類似於透過 REST API 在 Chat Completions 中傳送使用者訊息(提示詞)。

以使用者輸入建立對話項目
const event = {
  type: "conversation.item.create",
  item: {
    type: "message",
    role: "user",
    content: [
      {
        type: "input_text",
        text: "What Prince album sold the most copies?",
      },
    ],
  },
};

// WebRTC data channel and WebSocket both have .send()
ws.send(JSON.stringify(event));

將使用者訊息加入對話後,傳送 response.create 事件,讓模型開始生成回應。請選擇一種輸出模態:audio 會產生音訊及其轉錄文字,text 則只會產生文字。如果只需要文字,可以在傳送 response.create 用戶端事件時指定,如下所示。

生成純文字回應
const event = {
  type: "response.create",
  response: {
    output_modalities: ["text"],
  },
};

// WebRTC data channel and WebSocket both have .send()
ws.send(JSON.stringify(event));

回應全部生成完畢後,伺服器會發出 response.done 事件。此事件包含模型生成的完整文字,如下所示。

監聽 response.done 以取得最終結果
function handleEvent(message: import("ws").RawData | MessageEvent<string>) {
  const data = "data" in message ? message.data : message.toString();
  const serverEvent = JSON.parse(data);
  if (serverEvent.type === "response.done") {
    console.log(serverEvent.response.output[0]);
  }
}

// Listen for server messages (WebRTC)
// dataChannel.addEventListener("message", handleEvent);

// Listen for server messages (WebSocket)
ws.on("message", handleEvent);

模型生成回應的過程中,伺服器會發出一系列生命週期事件。你可以監聽 response.output_text.delta 等事件,在生成回應時即時向使用者顯示進度。下表的相關伺服器事件欄列出伺服器發出的所有事件,大致依發出順序排列。表中也列出生成文字時相關的用戶端事件。

音訊輸入與輸出

Realtime API 的一項強大功能,是讓使用者直接以語音與模型互動,無須經過文字轉語音或語音轉文字的中間步驟。這能降低語音介面的延遲,也讓模型能運用語音輸入中的更多資訊,例如說話者的語氣與音調變化。

聲音選項

Realtime 工作階段提供多種內建聲音,可選擇其中一種產生音訊輸出。你可以設定 voice 來決定模型說話的聲音。這項設定可在建立工作階段時指定,也可在 response.create 事件中指定。目前可選用 alloy、ash、ballad、coral、echo、sage、shimmer、verse、marin 和 cedar。模型一旦在工作階段中輸出音訊,就無法再變更該工作階段的 voice。如需最佳音質,建議使用 marin 或 cedar。

使用 WebRTC 處理音訊

使用 WebRTC 連上 Realtime API 時,Realtime API 會與用戶端建立對等連線。模型輸出的音訊會以遠端媒體串流傳送至用戶端。傳給模型的音訊則透過音訊裝置擷取(使用 getUserMedia),再將媒體串流以軌道的形式加入對等連線。

WebRTC 連線指南中的下列程式碼示範如何使用瀏覽器 API 設定本機與遠端音訊:

// Create a peer connection
const pc = new RTCPeerConnection();

// Set up to play remote audio from the model
const audioEl = document.createElement("audio");
audioEl.autoplay = true;
pc.ontrack = (e) => (audioEl.srcObject = e.streams[0]);

// Add local audio track for microphone input in the browser
const ms = await navigator.mediaDevices.getUserMedia({
  audio: true,
});
pc.addTrack(ms.getTracks()[0]);

使用上述程式碼即可與 Realtime API 互動。若要進一步探索不同類型的使用者介面,可參閱 WebRTC 範例程式碼庫,也可以線上體驗這些範例。

使用瀏覽器的媒體擷取與串流 API,就能開啟或關閉麥克風、選擇擷取輸入的裝置,以及執行其他操作。

WebRTC 音訊的用戶端與伺服器事件

依預設,WebRTC 用戶端在傳送音訊輸入前,無須向 Realtime API 傳送任何用戶端事件。只要將本機音軌加入對等連線,使用者就可以開始說話。

不過,當用戶端與伺服器透過對等連線收發音訊時,WebRTC 用戶端仍會收到伺服器發出的一系列生命週期事件,例如:

使用 WebRTC API 操作媒體串流,可能就足以滿足你的控制需求。不過,有時仍需要透過較低階的介面處理音訊輸入與輸出。下方的 WebSocket 一節提供更多資訊,並列出精細控制音訊輸入所需的事件。

使用 WebSocket 處理音訊

透過 WebSocket 收發音訊時,用戶端需要執行更多操作,才能將媒體傳給伺服器並接收伺服器傳回的媒體。下表列出在 WebSocket 工作階段中收發音訊所需的事件流程。

下列事件依生命週期順序排列,但有些事件(例如 delta 事件)可能同時發生。

將音訊輸入串流傳送至伺服器

若要將音訊輸入串流傳送至伺服器,可以使用 input_audio_buffer.append 用戶端事件。使用此事件時,需要透過 WebSocket 將以 Base64 編碼的音訊位元組分段傳送至 Realtime API。每段大小不得超過 15 MB。

請設定 session.audio.input.format,並透過 session.update 套用設定。若使用 PCM,請指定 {"type": "audio/pcm", "rate": 24000},並傳送 24 kHz 的單聲道音訊。

將音訊輸入位元組附加至對話
import fs from "fs";
import decodeAudio from "audio-decode";

// Converts Float32Array of audio data to PCM16 ArrayBuffer
function floatTo16BitPCM(float32Array: Float32Array) {
  const buffer = new ArrayBuffer(float32Array.length * 2);
  const view = new DataView(buffer);
  let offset = 0;
  for (let i = 0; i < float32Array.length; i++, offset += 2) {
    const sample = Math.max(-1, Math.min(1, float32Array[i]));
    view.setInt16(
      offset,
      Math.round(sample * (sample < 0 ? 0x8000 : 0x7fff)),
      true
    );
  }
  return buffer;
}

// Converts a Float32Array to base64-encoded PCM16 data
function base64EncodeAudio(float32Array: Float32Array<ArrayBufferLike>) {
  const arrayBuffer = floatTo16BitPCM(float32Array);
  let binary = "";
  let bytes = new Uint8Array(arrayBuffer);
  const chunkSize = 0x8000; // 32KB chunk size
  for (let i = 0; i < bytes.length; i += chunkSize) {
    let chunk = bytes.subarray(i, i + chunkSize);
    binary += String.fromCharCode(...chunk);
  }
  return btoa(binary);
}

// Fills the audio buffer with the contents of three files,
// then asks the model to generate a response.
const files = [
  "fixtures/sample1.wav",
  "fixtures/sample2.wav",
  "fixtures/sample3.wav",
];

// Manual commit and response creation require automatic turn detection off.
ws.send(
  JSON.stringify({
    type: "session.update",
    session: {
      type: "realtime",
      audio: { input: { turn_detection: null } },
    },
  })
);

for (const filename of files) {
  const audioFile = fs.readFileSync(filename);
  const audioBuffer = await decodeAudio(audioFile);
  if (
    audioBuffer.sampleRate !== 24000 ||
    audioBuffer.channelData.length !== 1
  ) {
    throw new Error("Expected 24 kHz mono audio: " + filename);
  }
  const channelData = audioBuffer.channelData[0];
  const base64Chunk = base64EncodeAudio(channelData);
  ws.send(
    JSON.stringify({
      type: "input_audio_buffer.append",
      audio: base64Chunk,
    })
  );
}

ws.send(JSON.stringify({ type: "input_audio_buffer.commit" }));
ws.send(
  JSON.stringify({
    type: "response.create",
    response: { output_modalities: ["audio"] },
  })
);

傳送完整音訊訊息

你也可以用整段錄音建立對話訊息。使用 conversation.item.create 用戶端事件,即可建立包含 input_audio 內容的訊息。

以完整錄音建立音訊輸入對話項目
const fullAudio = "<a base64-encoded string of audio bytes>";

const event = {
  type: "conversation.item.create",
  item: {
    type: "message",
    role: "user",
    content: [
      {
        type: "input_audio",
        audio: fullAudio,
      },
    ],
  },
};

// WebRTC data channel and WebSocket both have .send()
dataChannel.send(JSON.stringify(event));

處理透過 WebSocket 接收的音訊輸出

若要在網頁瀏覽器等用戶端環境播放輸出音訊,建議優先使用 WebRTC,而非 WebSocket。在網路狀況不穩定時,WebRTC 能更可靠地將媒體傳送至用戶端裝置。

在伺服器對伺服器的應用程式中,若要使用 WebSocket 處理音訊輸出,需要監聽 response.output_audio.delta 事件。每個事件都包含模型輸出的一段音訊資料,並以 Base64 編碼。你可以先將這些資料存入緩衝區,再寫入檔案,也可以立即將資料串流傳送至其他目的地,例如 Twilio 電話通話。

請注意,response.output_audio.done 和 response.done 事件只包含音訊的轉錄文字,不含音訊資料。若要取得實際的音訊位元組,需要監聽 response.output_audio.delta 事件。

輸出音訊片段的格式可以針對整個工作階段設定,也可以逐一為回應設定。

  • 工作階段:使用 session.audio.output.format 欄位,在 session.update 中設定。
  • 回應:使用 response.audio.output.format 欄位,在 response.create 中設定。
監聽 response.output_audio.delta 事件
function handleEvent(message: { toString: () => string }) {
  const serverEvent = JSON.parse(message.toString());
  if (serverEvent.type === "response.output_audio.delta") {
    const audio = Buffer.from(serverEvent.delta, "base64");
    console.log(`Received ${audio.length} audio bytes`);
  }
}

// Listen for server messages (WebSocket)
ws.on("message", handleEvent);

圖片輸入

gpt-realtime-2 和 gpt-realtime 也支援圖片輸入。你可以在使用者訊息中附上圖片,作為訊息內容的一部分,模型便能在回應時參考圖片內容。

將圖片加入對話
const base64Image = "<a base64-encoded string of image bytes>";

const event = {
  type: "conversation.item.create",
  item: {
    type: "message",
    role: "user",
    content: [
      {
        type: "input_image",
        image_url: `data:image/{format};base64,${base64Image}`,
      },
    ],
  },
};

// WebRTC data channel and WebSocket both have .send()
dataChannel.send(JSON.stringify(event));

語音活動偵測

Realtime 工作階段預設啟用語音活動偵測(VAD)。API 會判斷使用者何時開始或停止說話,並自動回應。

如需瞭解如何設定 VAD,請參閱語音活動偵測指南。

停用 VAD

將 turn_detection 設為 null,再透過 session.update 用戶端事件套用設定,即可停用 VAD。這適用於需要精細控制音訊輸入的介面,例如按住說話介面。

停用 VAD 後,用戶端必須手動發出以下額外事件,才能觸發音訊回應:

保留 VAD,但停用自動回應

如果想繼續使用 VAD,但希望自行決定何時生成回應,可以將 turn_detection.interrupt_response 和 turn_detection.create_response 設為 false,再透過 session.update 用戶端事件套用設定。這會保留 VAD 的所有偵測行為,但不會自動建立新的回應。用戶端可以透過 response.create 事件手動觸發回應。

這適用於內容審核、輸入驗證或 RAG 等情境,讓你以稍長的互動延遲換取對輸入的控制。

在預設對話以外建立回應

依預設,在工作階段中生成的所有回應都會加入該工作階段的對話狀態(即「預設對話」)。不過,你可能希望模型在預設對話的上下文之外生成回應,或同時生成多個回應。你也可能希望更精確地控制模型在生成回應時參考哪些對話項目,例如只參考最近 N 輪對話。

將 response.conversation 欄位設為字串 none,再透過 response.create 用戶端事件建立回應,即可生成「帶外」回應。這類回應不會加入預設對話狀態。

建立帶外回應時,通常也需要辨識伺服器傳送的哪些事件與該回應有關。你可以為模型回應提供 metadata,以便辨識模型正在為這個用戶端事件生成哪個回應。

建立帶外模型回應
const prompt = `
Analyze the conversation so far. If it is related to support, output
"support". If it is related to sales, output "sales".
`;

  const event = {
    type: "response.create",
    response: {
      // Setting to "none" indicates the response is out of band
      // and will not be added to the default conversation
      conversation: "none",

      // Set metadata to help identify responses sent back from the model
      metadata: { topic: "classification" },

      // Set any other available response fields
      output_modalities: ["text"],
      instructions: prompt,
    },
  };

  // WebRTC data channel and WebSocket both have .send()
  ws.send(JSON.stringify(event));

這樣一來,監聽 response.done 伺服器事件時,就能辨識出帶外回應的結果。

建立帶外模型回應
function handleEvent(message: import("ws").RawData | MessageEvent<string>) {
  const data = "data" in message ? message.data : message.toString();
  const serverEvent = JSON.parse(data);
  if (
    serverEvent.type === "response.done" &&
    serverEvent.response.metadata?.topic === "classification"
  ) {
    const { response } = serverEvent;
    if (response.status !== "completed" || response.output.length === 0) {
      throw new Error(
        "Classification response ended with status " + response.status
      );
    }
    console.log(response.output[0]);
  }
}

// Listen for server messages (WebRTC)
// dataChannel.addEventListener("message", handleEvent);

// Listen for server messages (WebSocket)
ws.on("message", handleEvent);

為回應建立自訂上下文

你也可以在目前的預設對話以外建立自訂上下文,讓模型據以生成回應。做法是使用 input 陣列,並在 response.create 用戶端事件中傳送。你可以提供新的輸入,也可以透過 ID 參照對話中既有的輸入項目。

監聽使用自訂上下文的帶外模型回應
const existingItemId = "item_pizza";
ws.send(
  JSON.stringify({
    type: "conversation.item.create",
    item: {
      id: existingItemId,
      type: "message",
      role: "user",
      content: [
        { type: "input_text", text: "We are ordering pizza for dinner." },
      ],
    },
  })
);
const event = {
  type: "response.create",
  response: {
    conversation: "none",
    metadata: { topic: "pizza" },
    output_modalities: ["text"],

    // Create a custom input array for this request with whatever context
    // is appropriate
    input: [
      // potentially include existing conversation items:
      {
        type: "item_reference",
        id: existingItemId,
      },
      {
        type: "message",
        role: "user",
        content: [
          {
            type: "input_text",
            text: "Is it okay to put pineapple on pizza?",
          },
        ],
      },
    ],
  },
};

// WebRTC data channel and WebSocket both have .send()
ws.send(JSON.stringify(event));

建立不含上下文的回應

你也可以讓模型忽略所有其他指示與上下文,再將回應插入預設對話。只要將 input 設為空陣列即可。

將不含上下文的模型回應插入預設對話
const prompt = `
Say exactly the following:
I'm a little teapot, short and stout!
This is my handle, this is my spout!
`;

  const event = {
    type: "response.create",
    response: {
      // An empty input array removes existing context
      input: [],
      output_modalities: ["text"],
      instructions: prompt,
    },
  };

  // WebRTC data channel and WebSocket both have .send()
  ws.send(JSON.stringify(event));

函式呼叫

Realtime 模型也支援函式呼叫,讓你能執行自訂程式碼來擴充模型功能。基本流程如下:

  1. 更新工作階段或建立回應時,可以指定模型可呼叫的函式清單。
  2. 模型處理輸入時,如果判斷需要呼叫函式,就會在對話中新增項目,列出要傳給函式的引數。
  3. 用戶端偵測到含有函式呼叫引數的對話項目後,會使用這些引數執行自訂程式碼。
  4. 自訂程式碼執行完畢後,用戶端會建立包含函式呼叫結果的新對話項目,並要求模型回應。

以下範例會新增一個模型可呼叫的函式,為使用者提供今日星座運勢。範例會示範需要傳送的用戶端事件物件格式,以及伺服器接著會發出的事件。

設定可呼叫的函式

首先,必須提供一組函式,讓模型根據使用者輸入選擇要呼叫的函式。可用函式可以針對整個工作階段設定,也可以針對個別回應設定。

  • 工作階段:使用 session.tools 屬性,在 session.update 中設定。
  • 回應:使用 response.tools 屬性,在 response.create 中設定。

以下是 session.update 用戶端事件的資料範例。它會設定一個生成星座運勢的函式,該函式只接受一個引數,即要查詢運勢的星座:

session.update

{
  "type": "session.update",
  "session": {
    "tools": [
      {
        "type": "function",
        "name": "generate_horoscope",
        "description": "Give today's horoscope for an astrological sign.",
        "parameters": {
          "type": "object",
          "properties": {
            "sign": {
              "type": "string",
              "description": "The sign for the horoscope.",
              "enum": [
                "Aries",
                "Taurus",
                "Gemini",
                "Cancer",
                "Leo",
                "Virgo",
                "Libra",
                "Scorpio",
                "Sagittarius",
                "Capricorn",
                "Aquarius",
                "Pisces"
              ]
            }
          },
          "required": ["sign"]
        }
      }
    ],
    "tool_choice": "auto"
  }
}

函式與參數各自的 description 欄位可協助模型判斷是否要呼叫該函式,以及每個參數應傳入哪些資料。如果模型收到的輸入表示使用者想查詢自己的星座運勢,就會使用 sign 參數呼叫此函式。

偵測模型何時要呼叫函式

模型可能會根據收到的輸入,決定呼叫函式以生成最合適的回應。假設應用程式透過 conversation.item.create 事件新增以下對話項目,然後建立回應:

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "我是水瓶座,今天的運勢如何?"
      }
    ]
  }
}

接著傳送 response.create 用戶端事件,讓模型生成回應:

{
  "type": "response.create"
}

此時,模型不會立即傳回文字或音訊,而會生成一個包含函式引數的回應,供開發者的應用程式將引數傳給指定函式。你可以監聽 response.function_call_arguments.delta 伺服器事件,即時取得函式呼叫引數的更新。response.done 也會包含呼叫函式所需的完整資料。

response.done

{
  "type": "response.done",
  "event_id": "event_AeqLA8iR6FK20L4XZs2P6",
  "response": {
    "object": "realtime.response",
    "id": "resp_AeqL8XwMUOri9OhcQJIu9",
    "status": "completed",
    "status_details": null,
    "output": [
      {
        "object": "realtime.item",
        "id": "item_AeqL8gmRWDn9bIsUM2T35",
        "type": "function_call",
        "status": "completed",
        "name": "generate_horoscope",
        "call_id": "call_sHlR7iaFwQ2YQOqm",
        "arguments": "{\"sign\":\"Aquarius\"}"
      }
    ]
  }
}

從伺服器傳回的 JSON 可以判斷模型要呼叫自訂函式,並取得呼叫所需的資訊:

屬性 在函式呼叫中的用途
response.output[0].type 值為 function_call 時,表示此回應包含呼叫指定函式所需的引數。
response.output[0].name 要呼叫的已設定函式名稱,本例為 generate_horoscope。
response.output[0].arguments 包含函式引數的 JSON 字串,本例為 "{\"sign\":\"Aquarius\"}"。
response.output[0].call_id 系統為這次函式呼叫產生的 ID。將函式呼叫結果傳回模型時,需要使用這個 ID。

取得這些資訊後,就可以在應用程式中執行程式碼,產生星座運勢,再將結果傳回模型,讓模型據以生成回應。

將函式呼叫結果提供給模型

應用程式收到含有函式呼叫引數的模型回應後,即可執行程式碼來完成該次呼叫。你可以依需求實作函式,例如呼叫外部 API 或存取資料庫。

準備好將自訂程式碼的執行結果傳給模型後,可以透過 conversation.item.create 用戶端事件,建立包含結果的新對話項目。

{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "call_sHlR7iaFwQ2YQOqm",
    "output": "{\"horoscope\": \"You will soon meet a new friend.\"}"
  }
}
  • 對話項目的類型為 function_call_output。
  • item.call_id 必須與先前從 response.done 事件取得的呼叫 ID 相同。
  • item.output 是包含函式呼叫結果的 JSON 字串。

將含有函式呼叫結果的項目加入對話後,再從用戶端發出 response.create 事件。模型就會使用函式呼叫傳回的資料生成回應。

{
  "type": "response.create"
}

錯誤處理

工作階段進行期間,只要伺服器遇到錯誤,就會發出 error 事件。有些錯誤可以追溯到應用程式發出的用戶端事件。

在 HTTP 中,回應本身就對應到某個用戶端請求。使用 Realtime API 時,則需要在用戶端事件中加入 event_id 屬性,才能判斷是哪個事件在伺服器上觸發了錯誤。以下程式碼以用戶端嘗試發出不支援的事件類型為例,示範此做法。

const event = {
  event_id: "my_awesome_event",
  type: "scooby.dooby.doo",
};

dataChannel.send(JSON.stringify(event));

伺服器無法處理用戶端傳來的事件,因此會發出類似以下的錯誤事件:

{
  "type": "error",
  "event_id": "event_error_123",
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_value",
    "message": "Invalid value: 'scooby.dooby.doo'.",
    "param": "type",
    "event_id": "my_awesome_event"
  }
}

中斷與截斷

許多語音應用程式都允許使用者在模型說話時打斷它。啟用 VAD 時,Realtime API 會在偵測到使用者開口後取消正在生成的回應,並開始新的回應。此時,模型需要知道使用者在哪裡打斷它,才能自然地接續對話,例如在使用者問「你剛剛最後說了什麼?」時接著回答。這個做法稱為截斷模型的上一則回應,也就是從對話中移除該則回應尚未播放的部分。

使用 WebRTC 或 SIP 連線時,伺服器會管理輸出音訊緩衝區,因此能掌握每個時間點已播放的音訊長度。使用者打斷模型時,伺服器會自動截去尚未播放的音訊。

使用 WebSocket 連線時,音訊播放由用戶端管理,因此用戶端必須負責停止播放並處理截斷。流程如下:

  1. 收到 input_audio_buffer.speech_started 時,立即停止播放模型的音訊,並捨棄該項目中所有排隊等候播放的音訊。以毫秒為單位記錄使用者實際聽到的該項目音訊長度。
  2. 傳送 conversation.item.truncate 事件,附上遭中斷項目的 ID、音訊內容的索引,並將已播放的時長填入 audio_end_ms。這會從對話中移除尚未播放的部分。
  3. VAD 中斷正在生成的回應時,伺服器會取消該回應,並傳送 response.done,其中 response.status 的值為 cancelled。此事件可用來確認回應已結束。停止播放或傳送截斷事件前,請勿等待此事件。

範例如下:

{
  "type": "conversation.item.truncate",
  "item_id": "item_1234",
  "content_index": 0,
  "audio_end_ms": 1500
}

在這個範例中,音訊會在播放 1.5 秒處截斷。

轉錄文字也能在同一處截斷嗎?Realtime 模型掌握的資訊不足以將轉錄文字與音訊精確對齊,因此 conversation.item.truncate 會在指定位置截斷音訊,並移除尚未播放部分的轉錄文字。這能移除尚未播放的音訊,但不會提供截斷後的轉錄文字。

按住說話

Realtime API 預設使用語音活動偵測(VAD),根據音訊輸入觸發模型回應。你也可以停用 VAD,由應用程式控制何時將音訊輸入傳給模型,實作按住說話的互動方式。例如,按住空白鍵時擷取音訊,放開時觸發回應。這種方式在某些應用程式中特別有效:使用者能掌控互動時機,也能避免 VAD 偵測失敗,而且無須等待 VAD 逾時,操作起來更俐落。

使用 WebSocket 與 WebRTC 實作按住說話的方式略有不同。Realtime API 的 WebSocket 連線會透過同一個通道依序傳送所有事件,而 WebRTC 連線則使用不同通道傳送音訊與控制事件。

WebSocket

若要透過 WebSocket 連線實作按住說話,用戶端需要負責停止播放音訊、處理中斷及觸發新回應。詳細步驟如下:

  1. 指定 "turn_detection": null,並透過 session.update 事件套用設定,以停用 VAD。
  2. 按下按鍵時,在用戶端開始錄音。
    1. 如果模型正在生成回應,傳送 response.cancel 事件將其取消。
    2. 如果仍在播放模型輸出的音訊,立即停止播放,並傳送 conversation.item.truncate 事件,從對話中移除尚未播放的音訊。
  3. 放開按鍵時,傳送含有錄音的 input_audio_buffer.append 訊息,將新音訊加入輸入緩衝區。
  4. 傳送 input_audio_buffer.commit 事件,提交已寫入輸入緩衝區的音訊。如果已啟用輸入轉錄,也會開始轉錄。
  5. 接著傳送 response.create 事件來觸發回應。

WebRTC 與 SIP

使用 WebRTC 實作按住說話的方式類似,但必須明確清除輸入音訊緩衝區。步驟如下:

  1. 指定 "turn_detection": null,並透過 session.update 事件套用設定,以停用 VAD。
  2. 按下按鍵時,傳送 input_audio_buffer.clear 事件,清除先前的音訊輸入。
    1. 如果模型正在生成回應,傳送 response.cancel 事件將其取消。
    2. 如果仍在播放模型輸出的音訊,傳送 output_audio_buffer.clear 事件,清除尚未播放的音訊。這也會截斷對話中的相應內容。
  3. 放開按鍵時,傳送 input_audio_buffer.commit 事件,提交已寫入輸入緩衝區的音訊。如果已啟用輸入轉錄,也會開始轉錄。
  4. 接著傳送 response.create 事件來觸發回應。