語音即時 `2026-04-10` API 參考

Voice Live API 為使用 WebSocket 連線的語音應用程式提供即時、雙向通訊。

API 利用透過 WebSocket 連線傳送的 JSON 格式事件來管理對話、音訊串流、虛擬角色互動及即時回應。事件分為客戶端事件（從客戶端傳送到伺服器）和伺服器事件（從伺服器傳送到客戶端）。

端點與認證

WebSocket 端點

Voice Live API 的 WebSocket 端點為：

wss://<your-ai-foundry-resource-name>.services.ai.azure.com/voice-live/realtime?api-version=2026-04-10

對於使用舊有網域的舊資源，請使用：

wss://<your-ai-foundry-resource-name>.cognitiveservices.azure.com/voice-live/realtime?api-version=2026-04-10

所有模型的端點都相同。唯一的差別是所需的 model 查詢參數，或在使用 Microsoft Foundry Agent Service 時，使用 agent-name 和 agent-project-name 查詢參數。欲了解更多代理連線參數，請參閱 Integration Voice Live API with a Microsoft Foundry agent。

例如，使用 Microsoft Foundry 資源的端點會是：

wss://<your-ai-foundry-resource-name>.services.ai.azure.com/voice-live/realtime?api-version=2026-04-10&model=gpt-realtime

Note

Voice Live API 針對 Microsoft Foundry 資源進行優化。建議使用 Microsoft Foundry 資源以獲得完整功能。 Azure AI 語音資源不支援 Microsoft Foundry 代理服務整合或自帶模型（BYOM）。

Authentication

Voice Live API 支援兩種認證方式：

Microsoft Entra ID（建議）：對 Microsoft Foundry 資源使用基於憑證的認證。透過以下兩種方式傳遞取回的存取權杖：
- 作為 Bearer 預握連線標頭中的 Authorization 一個標記。這個選項在瀏覽器環境中沒有。
- 作為 Authorization 請求 URI 上的查詢字串參數，值為 Bearer <token>。根據需要對 URL 編碼該值。查詢字串參數由傳輸加密 wss:// 。
API 關鍵：提供， api-key 方式有兩種：
- 作為 api-key 預握手連線上的連線標頭。這個選項在瀏覽器環境中沒有。
- 作為 api-key 請求 URI 上的查詢字串參數。查詢字串參數由傳輸加密 wss:// 。

關於推薦的無鑰匙認證 Microsoft Entra ID：

將 Cognitive Services User 和 Azure AI User 角色指派給你的使用者帳號或管理身份。你可以在Azure入口網站的 存取控制（IAM）>新增角色分配下分配角色。
使用 Azure CLI 或 Azure SDK 取得存取權杖。該令牌必須為 https://ai.azure.com/.default 範圍（或舊有 https://cognitiveservices.azure.com/.default 範圍）發行。
在 WebSocket 升級請求中傳送標記，無論是格式 Authorization 的 Bearer <token>標頭，或以 Authorization 相同 Bearer <token> 值的查詢字串參數。

客戶活動

Voice Live API 支援以下客戶端事件，這些事件可從客戶端傳送至伺服器：

事件	Description
session.update	更新會話設定，包括語音、輸出模式、轉向偵測及其他設定
session.avatar.connect	透過提供客戶端 SDP 以進行 WebRTC 協商，建立頭像連線
input_audio_buffer.附加	將音訊位元組附加到輸入音訊緩衝區
input_audio_buffer.提交	提交輸入音訊緩衝區進行處理
input_audio_buffer.清除	清除輸入音訊緩衝區
conversation.item.create的	在對話情境中新增一項
conversation.item.檢索	從對話中擷取特定物品
對話.item.截斷	截斷助理語音訊息
conversation.item.刪除	從對話中移除一項內容
回應.create	指示伺服器透過模型推論產生回應
回應.取消	取消正在進行中的回應
output_audio_buffer.清場	透過清除伺服器端的音訊緩衝區（僅限虛擬角色模式）來阻止虛擬角色說話

session.update

更新會話的設定。此事件可隨時發送，以修改設定，如語音、輸出模式、轉向偵測、工具及其他會話參數。請注意，一旦會話初始化為特定模型，就無法再更改為其他模型。

活動結構

{
  "type": "session.update",
  "session": {
    "modalities": ["text", "audio"],
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "instructions": "You are a helpful assistant. Be concise and friendly.",
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "turn_detection": {
      "type": "azure_semantic_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 420,
      "silence_duration_ms": 500
    },
    "temperature": 0.8,
    "max_response_output_tokens": "inf"
  }
}

屬性

Field	類型	Description
型別	字串	必須是 `"session.update"`
工作階段	RealtimeRequestSession	帶有可更新欄位的會話設定物件

以 Azure 自訂語音為例

{
  "type": "session.update",
  "session": {
    "voice": {
      "type": "azure-custom",
      "name": "my-custom-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012",
      "temperature": 0.7,
      "style": "cheerful"
    },
    "input_audio_noise_reduction": {
      "type": "azure_deep_noise_suppression"
    },
    "avatar": {
      "character": "lisa",
      "customized": false,
      "video": {
        "resolution": {
          "width": 1920,
          "height": 1080
        },
        "bitrate": 2000000
      }
    }
  }
}

session.avatar.connect

透過提供客戶端的 SDP（會話描述協議）來建立虛擬化身連線，用於 WebRTC 媒體協商。使用虛擬化身功能時必須發生此事件。

活動結構

{
  "type": "session.avatar.connect",
  "client_sdp": "<client_sdp>"
}

屬性

Field	類型	Description
型別	字串	必須是 `"session.avatar.connect"`
client_sdp	字串	客戶端的 SDP 提供用於 WebRTC 連線建立的方案，以 base64 編碼

input_audio_buffer.附加

在輸入音訊緩衝區中加入音訊位元組。

活動結構

{
  "type": "input_audio_buffer.append",
  "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA="
}

屬性

Field	類型	Description
型別	字串	必須是 `"input_audio_buffer.append"`
音效	字串	Base64 編碼的音訊資料

input_audio_buffer.提交

將輸入音訊緩衝區提交進行處理。

活動結構

{
  "type": "input_audio_buffer.commit"
}

屬性

Field	類型	Description
型別	字串	必須是 `"input_audio_buffer.commit"`

input_audio_buffer.清除

清除輸入音訊緩衝區。

活動結構

{
  "type": "input_audio_buffer.clear"
}

屬性

Field	類型	Description
型別	字串	必須是 `"input_audio_buffer.clear"`

conversation.item.create

在對話情境中新增一個項目。這可以包括訊息、函式呼叫和函式呼叫回應。項目可插入對話歷史中的特定位置。

活動結構

{
  "type": "conversation.item.create",
  "previous_item_id": "item_ABC123",
  "item": {
    "id": "item_DEF456",
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Hello, how are you?"
      }
    ]
  }
}

屬性

Field	類型	Description
型別	字串	必須是 `"conversation.item.create"`
前項目ID	字串	Optional. 物品的識別碼，然後插入該物品。若未提供，則附錄結束
項目	即時會話請求項目	要加入對話的項目

音訊內容範例

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_audio",
        "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA=",
        "transcript": "Hello there"
      }
    ]
  }
}

函式呼叫輸出的範例

{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "call_123",
    "output": "{\"location\": \"San Francisco\", \"temperature\": \"70\"}"
  }
}

MCP 核准回應範例

{
  "type": "conversation.item.create",
  "item": {
    "type": "mcp_approval_response",
    "approval_request_id": "mcp_approval_req_456",
    "approve": true,
  }
}

conversation.item.檢索

從對話紀錄中擷取特定項目。這對於在降噪和 VAD 後檢查處理過的音訊很有用。

活動結構

{
  "type": "conversation.item.retrieve",
  "item_id": "item_ABC123"
}

屬性

Field	類型	Description
型別	字串	必須是 `"conversation.item.retrieve"`
item_id	字串	要取回的物品 ID

對話.item.截斷

截斷助理訊息的音訊內容。這對於在特定時間點停止播放以及同步伺服器與客戶端狀態的理解非常有用。

活動結構

{
  "type": "conversation.item.truncate",
  "item_id": "item_ABC123",
  "content_index": 0,
  "audio_end_ms": 5000
}

屬性

Field	類型	Description
型別	字串	必須是 `"conversation.item.truncate"`
item_id	字串	要截斷的助理訊息項目的 ID
content_index	整數	內容部分的索引要被截斷
audio_end_ms	整數	截斷音訊的長度，以毫秒為單位

刪除会话项

從對話紀錄中移除一項項目。

活動結構

{
  "type": "conversation.item.delete",
  "item_id": "item_ABC123"
}

屬性

Field	類型	Description
型別	字串	必須是 `"conversation.item.delete"`
item_id	字串	要刪除的項目 ID

回應.建立

指示伺服器透過模型推理建立回應。此事件可指定針對回應的設定，覆蓋會話預設值。

活動結構

{
  "type": "response.create",
  "response": {
    "modalities": ["text", "audio"],
    "instructions": "Be extra helpful and detailed.",
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "output_audio_format": "pcm16",
    "temperature": 0.7,
    "max_response_output_tokens": 1000
  }
}

屬性

Field	類型	Description
型別	字串	必須是 `"response.create"`
response	RealtimeResponseOptions	可選的回應設定可覆蓋會話預設值

工具選擇的範例

{
  "type": "response.create",
  "response": {
    "modalities": ["text"],
    "tools": [
      {
        "type": "function",
        "name": "get_current_time",
        "description": "Get the current time",
        "parameters": {
          "type": "object",
          "properties": {}
        }
      }
    ],
    "tool_choice": "get_current_time",
    "temperature": 0.3
  }
}

動畫範例

{
  "type": "response.create",
  "response": {
    "modalities": ["audio", "animation"],
    "animation": {
      "model_name": "default",
      "outputs": ["blendshapes", "viseme_id"]
    },
    "voice": {
      "type": "azure-custom",
      "name": "my-expressive-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012",
      "style": "excited"
    }
  }
}

預先產生的助理訊息範例

在某些情況下，你可能會想為預設文字產生音訊回應，而不是讓模型自動產生文字回應。請使用 pre_generated_assistant_message 訊息中的 response.create 參數。欄位中只能包含一個文字條目 content 。

{
  "type": "response.create",
  "response": {
    "pre_generated_assistant_message": {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "repeat what I say"
        }
      ]
    }
  }
}

當服務收到此訊息時，會針對預設文字產生音訊回應。該訊息也會被加入對話的上下文歷史紀錄中。

回應.取消

取消進行中的回應。這會立即停止回應產生及相關音訊輸出。

活動結構

{
  "type": "response.cancel"
}

屬性

Field	類型	Description
型別	字串	必須是 `"response.cancel"`

output_audio_buffer.清除

清除伺服器端的輸出音訊緩衝區。在目前預覽版中，此事件僅支援虛擬化身模式，並用來清除伺服器排隊播放的任何音訊（及相應的虛擬化身影片）來阻止虛擬化身發言。伺服器會 output_audio_buffer.cleared 以事件回應。

活動結構

{
  "type": "output_audio_buffer.clear"
}

屬性

Field	類型	Description
型別	字串	必須是 `"output_audio_buffer.clear"`

input_audio_buffer.附加

用戶端 input_audio_buffer.append 事件用於將音訊位元組附加到輸入音訊緩衝區。音訊緩衝區是一個暫時的儲存空間，可供寫入並在之後提交。

在伺服器 VAD（語音活動偵測）模式下，音訊緩衝區用於偵測語音，伺服器決定何時提交。當伺服器 VAD 被停用時，客戶端可選擇每個事件中要放置多少音訊，最多可達 15 MiB。例如，從用戶端串流較小的區塊，可以讓 VAD 的反應更快。

與大多數其他客戶端事件不同，伺服器不會對客戶端 input_audio_buffer.append 事件發送確認回應。

事件結構

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

屬性

Field	類型	Description
型別	字串	事件類型必須為 `input_audio_buffer.append`。
音效	字串	Base64編碼的音訊位元組。此值必須依照會話設定欄位所指定的 `input_audio_format` 格式。

input_audio_buffer.清除

用戶端 input_audio_buffer.clear 事件用於清除緩衝區中的音訊位元組。

伺服器會 input_audio_buffer.cleared 以事件回應。

事件結構

{
  "type": "input_audio_buffer.clear"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `input_audio_buffer.clear`。

input_audio_buffer.提交

用戶端 input_audio_buffer.commit 事件用來提交使用者輸入的音訊緩衝區，進而在對話中建立新的使用者訊息項目。若 input_audio_transcription 為該會話設定，音訊會被轉錄。

在伺服器 VAD 模式下，用戶端不需要傳送此事件，伺服器會自動提交音訊緩衝區。若沒有伺服器 VAD，用戶端必須提交音訊緩衝區才能建立使用者訊息項目。若輸入音訊緩衝區為空，此用戶端事件會產生錯誤。

提交輸入音訊緩衝區不會產生模型的回應。

伺服器會 input_audio_buffer.committed 以事件回應。

事件結構

{
  "type": "input_audio_buffer.commit"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `input_audio_buffer.commit`。

伺服器事件

Voice Live API 會傳送以下伺服器事件，以向用戶端傳達狀態、回應及資料：

事件	Description
error	表示處理過程中發生錯誤
警告	表示有警告發生，但不會打斷對話流程
session.created	當新會話成功建立時會傳送
session.updated	會話設定更新時會傳送
session.avatar.connecting	表示虛擬角色 WebRTC 連線正在建立中
會話項目已建立	當對話中新增項目時會發送
conversation.item.檢索	回應 conversation.item.retrieve 請求
conversation.item.截斷	確認項目截斷
conversation.item.已刪除	確認項目刪除
conversation.item.input_audio_transcription.已完成	輸入音訊轉錄完成
conversation.item.input_audio_transcription.delta	串流輸入音訊轉錄
conversation.item.input_audio_transcription.失敗	輸入音訊轉錄失敗
input_audio_buffer.承諾	輸入音訊緩衝區用於處理
input_audio_buffer.已清除	輸入音訊緩衝區已清除
input_audio_buffer.speech_started	輸入音訊緩衝區（VAD）偵測語音
input_audio_buffer.speech_stopped	語音在輸入音訊緩衝區（VAD）結束
response.created	新的回應產生開始
回應已完成	回應產生已完成
response.output_item.added	新增輸出項目加入回應
回應.輸出項目.完成	輸出項目已完成
response.content_part.新增	新增內容部分到輸出項目
response.content_part.完成	內容部分已完成
response.text.delta	從模型串流文字內容
回應.text.done	文字內容已完整
response.audio_transcript.delta	串流音訊逐字稿
response.audio_transcript.完成	音頻逐字稿已完整
回應.audio.delta	從模型串流音訊內容
回應.audio.done	音訊內容已完整
response.animation_blendshapes.delta	串流動畫混合形狀資料
response.animation_blendshapes.完成	動畫混合形狀的資料已完成
response.audio_timestamp.delta	串流音訊時間戳記資訊
response.audio_timestamp.完成	音訊時間戳記資訊已完整
response.animation_viseme.delta	串流動畫 viseme 資料
response.animation_viseme.完成	動畫 viseme 資料已完成
response.function_call_arguments.delta	串流函數呼叫參數
response.function_call_arguments.完成	函式呼叫參數是完備的
mcp_list_tools.in_progress（進行中）	MCP 工具列表正在進行中
mcp_list_tools。已完成	MCP 工具列表已完成
mcp_list_tools.失敗	MCP 工具列表已失敗
response.mcp_call_arguments.delta	串流 MCP 呼叫參數
response.mcp_call_arguments完成	MCP 呼叫參數已完成
response.mcp_call.in_progress（進行中）	MCP通話正在進行中
response.mcp_call。完成	MCP 通話已完成
response.mcp_call.失敗	MCP 呼叫失敗
response.foundry_agent_call_arguments.delta	串流鑄造代理呼叫參數
response.foundry_agent_call_arguments。完成	Foundry agent 呼叫參數已完成
response.foundry_agent_call進行中	鑄造廠代理人通話正在進行中
response.foundry_agent_call。已完成	鑄造廠代理通話完成
response.foundry_agent_call.失敗	鑄造廠代理人電話失敗
session.avatar.switch_to_speaking	阿凡達轉為會說話的狀態
session.avatar.switch_to_idle	阿凡達進入待機狀態
response.video.delta	串流虛擬化身影片影格資料
response.web_search_call.搜尋	網路搜尋工具的呼叫是搜尋
response.web_search_call進行中	網路搜尋工具徵集正在進行中
response.web_search_call。已完成	網路搜尋工具呼叫完成
response.file_search_call.搜尋	檔案搜尋工具呼叫正在搜尋
response.file_search_call.in_progress（進行中）	檔案搜尋工具的呼叫正在進行中
response.file_search_call。完成	檔案搜尋工具的呼叫完成
output_audio_buffer。清場	輸出音訊緩衝區已清除
response.audio_transcript.annotation.added	在音頻逐字稿中加入了註解

session.created

當新會話成功建立時會傳送。這是連接 API 後收到的第一個事件。

活動結構

{
  "type": "session.created",
  "session": {
    "id": "sess_ABC123DEF456",
    "object": "realtime.session",
    "model": "gpt-realtime",
    "modalities": ["text", "audio"],
    "instructions": "You are a helpful assistant.",
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "turn_detection": {
      "type": "azure_semantic_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 420,
      "silence_duration_ms": 500
    },
    "temperature": 0.8,
    "max_response_output_tokens": "inf"
  }
}

屬性

Field	類型	Description
型別	字串	必須是 `"session.created"`
工作階段	RealtimeResponseSession	所建立的會話物件

session.updated

當會話設定成功更新並 session.update 回應客戶端事件時發送。

活動結構

{
  "type": "session.updated",
  "session": {
    "id": "sess_ABC123DEF456",
    "voice": {
      "type": "azure-custom",
      "name": "my-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012"
    },
    "temperature": 0.7,
    "avatar": {
      "character": "lisa",
      "customized": false
    }
  }
}

屬性

Field	類型	Description
型別	字串	必須是 `"session.updated"`
工作階段	RealtimeResponseSession	更新後的會話物件

session.avatar.connecting

表示正在建立虛擬化身的 WebRTC 連線。此事件是回應 session.avatar.connect 客戶事件而發送的。

活動結構

{
  "type": "session.avatar.connecting",
  "server_sdp": "<server_sdp>"
}

屬性

Field	類型	Description
型別	字串	必須是 `"session.avatar.connecting"`

對話項目已創建

當對話中新增項目時，無論是透過客戶 conversation.item.create 事件或回應生成時自動發送。

活動結構

{
  "type": "conversation.item.created",
  "previous_item_id": "item_ABC123",
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Hello, how are you?"
      }
    ]
  }
}

屬性

Field	類型	Description
型別	字串	必須是 `"conversation.item.created"`
前項目ID	字串	插入該項目後方的項目識別碼
項目	RealtimeConversationResponseItem	已建立的對話項目

音訊項目範例

{
  "type": "conversation.item.created",
  "item": {
    "id": "item_GHI789",
    "type": "message",
    "status": "completed",
    "role": "user",
    "content": [
      {
        "type": "input_audio",
        "audio": null,
        "transcript": "What's the weather like today?"
      }
    ]
  }
}

conversation.item.檢索

conversation.item.retrieve回應客戶事件，提供所要求的對話項目。

活動結構

{
  "type": "conversation.item.retrieved",
  "item": {
    "id": "item_ABC123",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "audio",
        "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA=",
        "transcript": "Hello! I'm doing well, thank you for asking. How can I help you today?"
      }
    ]
  }
}

屬性

Field	類型	Description
型別	字串	必須是 `"conversation.item.retrieved"`
項目	RealtimeConversationResponseItem	已檢索的對話項目

conversation.item.已截斷

conversation.item.truncated當用戶端以事件截斷先前的助理音訊訊息項目conversation.item.truncate時，伺服器事件會被回傳。此事件用於同步伺服器對音訊的理解與用戶端播放。

此事件會截斷音訊並移除伺服器端文字逐字稿，確保上下文中沒有使用者不知情的文字。

事件結構

{
  "type": "conversation.item.truncated",
  "item_id": "<item_id>",
  "content_index": 0,
  "audio_end_ms": 0
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `conversation.item.truncated`。
item_id	字串	被截斷的助理訊息項目的 ID。
content_index	整數	內容部分的索引被截斷了。
audio_end_ms	整數	音訊被截斷的長度以毫秒為單位。

conversation.item.已刪除

conversation.item.delete回覆客戶事件，確認該項目已從對話中移除。

活動結構

{
  "type": "conversation.item.deleted",
  "item_id": "item_ABC123"
}

屬性

Field	類型	Description
型別	字串	必須是 `"conversation.item.deleted"`
item_id	字串	已刪除項目的識別碼

回應.已建立

當新的回應世代開始時會發送。這是反應序列中的第一個事件。

活動結構

{
  "type": "response.created",
  "response": {
    "id": "resp_ABC123",
    "object": "realtime.response",
    "status": "in_progress",
    "status_details": null,
    "output": [],
    "usage": {
      "total_tokens": 0,
      "input_tokens": 0,
      "output_tokens": 0
    }
  }
}

屬性

Field	類型	Description
型別	字串	必須是 `"response.created"`
response	RealtimeResponse	所建立的回應物件

回應已完成

回應產生完成後會傳送。此事件包含最終回應，包含所有輸出項目與使用統計。

活動結構

{
  "type": "response.done",
  "response": {
    "id": "resp_ABC123",
    "object": "realtime.response",
    "status": "completed",
    "status_details": null,
    "output": [
      {
        "id": "item_DEF456",
        "object": "realtime.item",
        "type": "message",
        "status": "completed",
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"
          }
        ]
      }
    ],
    "usage": {
      "total_tokens": 87,
      "input_tokens": 52,
      "output_tokens": 35,
      "input_token_details": {
        "cached_tokens": 0,
        "text_tokens": 45,
        "audio_tokens": 7
      },
      "output_token_details": {
        "text_tokens": 15,
        "audio_tokens": 20
      }
    }
  }
}

屬性

Field	類型	Description
型別	字串	必須是 `"response.done"`
response	RealtimeResponse	完成的回應物件

response.output_item.新增

當生成過程中新增輸出項目時會發送。

活動結構

{
  "type": "response.output_item.added",
  "response_id": "resp_ABC123",
  "output_index": 0,
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "in_progress",
    "role": "assistant",
    "content": []
  }
}

屬性

Field	類型	Description
型別	字串	必須是 `"response.output_item.added"`
response_id	字串	此項目所屬回應的識別碼
output_index	整數	回應輸出陣列中項目的索引
項目	RealtimeConversationResponseItem	新增的輸出項目

response.output_item.已完成

當輸出項目完成時發送。

活動結構

{
  "type": "response.output_item.done",
  "response_id": "resp_ABC123",
  "output_index": 0,
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Hello! I'm doing well, thank you for asking."
      }
    ]
  }
}

屬性

Field	類型	Description
型別	字串	必須是 `"response.output_item.done"`
response_id	字串	此項目所屬回應的識別碼
output_index	整數	回應輸出陣列中項目的索引
項目	RealtimeConversationResponseItem	完成的輸出項目

response.content_part.新增

response.content_part.added當回應產生時，助理訊息項目新增內容部分時，伺服器事件會回傳。

活動結構

{
  "type": "response.content_part.added",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "text",
    "text": ""
  }
}

屬性

Field	類型	Description
型別	字串	必須是 `"response.content_part.added"`
response_id	字串	回應的識別
item_id	字串	該內容部分所屬物品的識別碼
output_index	整數	回應中項目的索引
content_index	整數	本項目中此內容部分的索引
組件	RealtimeContentPart	新增的內容部分

response.content_part.完成

response.content_part.done當內容部分在助理訊息項目中完成串流時，伺服器事件會被回傳。

當回應被中斷、不完整或取消時，此事件也會回傳。

活動結構

{
  "type": "response.content_part.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "text",
    "text": "Hello! I'm doing well, thank you for asking."
  }
}

屬性

Field	類型	Description
型別	字串	必須是 `"response.content_part.done"`
response_id	字串	回應的識別
item_id	字串	該內容部分所屬物品的識別碼
output_index	整數	回應中項目的索引
content_index	整數	本項目中此內容部分的索引
組件	RealtimeContentPart	已完成的內容部分

response.text.delta

從模型串流文字內容。隨著模型產生文字，逐步發送。

活動結構

{
  "type": "response.text.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "Hello! I'm"
}

屬性

Field	類型	Description
型別	字串	必須是 `"response.text.delta"`
response_id	字串	回應的識別
item_id	字串	物品識別
output_index	整數	回應中項目的索引
content_index	整數	內容部分索引
delta	字串	增量文字內容

回應.text.done

文字內容生成完成後傳送。

活動結構

{
  "type": "response.text.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"
}

屬性

Field	類型	Description
型別	字串	必須是 `"response.text.done"`
response_id	字串	回應的識別
item_id	字串	物品識別
output_index	整數	回應中項目的索引
content_index	整數	內容部分索引
收發簡訊	字串	全文內容

回應.audio.delta

從模型串流音訊內容。音訊以 base64 編碼資料提供。

活動結構

{
  "type": "response.audio.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA="
}

屬性

Field	類型	Description
型別	字串	必須是 `"response.audio.delta"`
response_id	字串	回應的識別
item_id	字串	物品識別
output_index	整數	回應中項目的索引
content_index	整數	內容部分索引
delta	字串	Base64 編碼的音訊資料區塊

回應.audio.done

音訊內容生成完成後傳送。

活動結構

{
  "type": "response.audio.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

屬性

Field	類型	Description
型別	字串	必須是 `"response.audio.done"`
response_id	字串	回應的識別
item_id	字串	物品識別
output_index	整數	回應中項目的索引
content_index	整數	內容部分索引

response.audio_transcript.delta

產生音訊內容的串流逐字稿。

活動結構

{
  "type": "response.audio_transcript.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "Hello! I'm doing"
}

屬性

Field	類型	Description
型別	字串	必須是 `"response.audio_transcript.delta"`
response_id	字串	回應的識別
item_id	字串	物品識別
output_index	整數	回應中項目的索引
content_index	整數	內容部分索引
delta	字串	增量逐字稿文字

response.audio_transcript.完成

音訊逐字稿生成完成後傳送。

活動結構

{
  "type": "response.audio_transcript.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "transcript": "Hello! I'm doing well, thank you for asking. How can I help you today?"
}

屬性

Field	類型	Description
型別	字串	必須是 `"response.audio_transcript.done"`
response_id	字串	回應的識別
item_id	字串	物品識別
output_index	整數	回應中項目的索引
content_index	整數	內容部分索引
文字記錄	字串	完整逐字稿全文

conversation.item.input_audio_transcription。已完成

伺服器 conversation.item.input_audio_transcription.completed 事件是寫入音訊緩衝區的語音轉錄結果。

當客戶端或伺服器（在模式） server_vad 提交輸入音訊緩衝區時，轉錄就開始了。轉錄會與回應產生非同步進行，因此此事件可能發生在回應事件之前或之後。

即時 API 模型以原生方式接受音訊，因此輸入轉譯是在個別語音辨識模型上執行的個別程式，例如 whisper-1。因此，逐字稿可能與模型的詮釋有所不同，應視為粗略指引。

事件結構

{
  "type": "conversation.item.input_audio_transcription.completed",
  "item_id": "<item_id>",
  "content_index": 0,
  "transcript": "<transcript>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `conversation.item.input_audio_transcription.completed`。
item_id	字串	包含音訊的使用者訊息項目的 ID。
content_index	整數	包含音訊的內容部分索引。
文字記錄	字串	轉錄文字。
logprobs	LogProbProperties 陣列	Optional. 轉錄標記的對數機率。
片語	轉錄片語陣列	Optional. 轉錄詞句包含時間資訊。

對話.項目.input_audio_transcription.delta

conversation.item.input_audio_transcription.delta當輸入音訊轉錄設定完成，且使用者訊息的轉錄請求正在進行時，伺服器事件會被回傳。此事件提供部分轉錄結果，隨時提供。

事件結構

{
  "type": "conversation.item.input_audio_transcription.delta",
  "item_id": "<item_id>",
  "content_index": 0,
  "delta": "<delta>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `conversation.item.input_audio_transcription.delta`。
item_id	字串	使用者訊息項目的 ID。
content_index	整數	包含音訊的內容部分索引。
delta	字串	增量轉錄文字。

conversation.item.input_audio_transcription.失敗

conversation.item.input_audio_transcription.failed當輸入音訊轉錄設定中，且使用者訊息的轉錄請求失敗時，伺服器事件會被回傳。此事件與其他事件分開 error ，讓客戶能辨識相關項目。

事件結構

{
  "type": "conversation.item.input_audio_transcription.failed",
  "item_id": "<item_id>",
  "content_index": 0,
  "error": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>"
  }
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `conversation.item.input_audio_transcription.failed`。
item_id	字串	使用者訊息項目的 ID。
content_index	整數	包含音訊的內容部分索引。
錯誤	物件	轉錄錯誤的細節。請參閱下表中的巢狀性質。

錯誤性質

Field	類型	Description
型別	字串	錯誤的類型。
字碼	字串	如果有錯誤代碼。
訊息	字串	一個人類可讀的錯誤訊息。
param	字串	參數與錯誤相關，若有的話。

response.animation_blendshapes.delta

response.animation_blendshapes.delta當模型在回應中產生動畫混合形狀資料時，伺服器事件會回傳。此事件會隨著混合形狀資料的增量提供。

事件結構

{
  "type": "response.animation_blendshapes.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "frame_index": 0,
  "frames": [
    [0.0, 0.1, 0.2, ..., 1.0]
    ...
  ]
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.animation_blendshapes.delta`。
response_id	字串	回應的識別
item_id	字串	物品識別
output_index	整數	回應中項目的索引
content_index	整數	內容部分索引
框架索引	整數	這批影格中第一個影格的索引
框架	浮點陣列的陣列	Blendshape 框架陣列，每個框架都是 blendshape 值的陣列

response.animation_blendshapes.完成

response.animation_blendshapes.done當模型完成作為回應一部分產生動畫混合形狀資料時，伺服器事件會回傳。

事件結構

{
  "type": "response.animation_blendshapes.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.animation_blendshapes.done`。
response_id	字串	回應的識別
item_id	字串	物品識別
output_index	整數	回應中項目的索引

response.audio_timestamp.delta

response.audio_timestamp.delta當模型在回應時產生音訊時間戳資料，伺服器事件即回傳。此事件提供增量時間戳資料，用於輸出音訊與文字的對齊，隨著資料開放。

事件結構

{
  "type": "response.audio_timestamp.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "audio_offset_ms": 0,
  "audio_duration_ms": 500,
  "text": "Hello",
  "timestamp_type": "word"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.audio_timestamp.delta`。
response_id	字串	回應的識別
item_id	字串	物品識別
output_index	整數	回應中項目的索引
content_index	整數	內容部分索引
audio_offset_ms	整數	音訊偏移（以毫秒計）從音訊開始開始
audio_duration_ms	整數	音訊片段的長度（毫秒）
收發簡訊	字串	對應此音訊時間戳記的文字段落
timestamp_type	字串	目前只支援「word」的時間戳記類型

response.audio_timestamp.完成

音訊時間戳記生成完成後傳送。

活動結構

{
  "type": "response.audio_timestamp.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.audio_timestamp.done`。
response_id	字串	回應的識別
item_id	字串	物品識別
output_index	整數	回應中項目的索引
content_index	整數	內容部分索引

response.animation_viseme.delta

response.animation_viseme.delta當模型在回應中產生動畫視覺資料時，伺服器事件會被回傳。此事件會隨著新增的視覺化資料提供。

活動結構

{
  "type": "response.animation_viseme.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "audio_offset_ms": 0,
  "viseme_id": 1
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.animation_viseme.delta`。
response_id	字串	回應的識別
item_id	字串	物品識別
output_index	整數	回應中項目的索引
content_index	整數	內容部分索引
audio_offset_ms	整數	音訊偏移（以毫秒計）從音訊開始開始
viseme_id	整數	對應於動畫嘴型的 viseme ID

response.animation_viseme.完成

response.animation_viseme.done當模型完成作為回應一部分產生動畫視覺資料時，伺服器事件會回傳。

活動結構

{
  "type": "response.animation_viseme.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.animation_viseme.done`。
response_id	字串	回應的識別
item_id	字串	物品識別
output_index	整數	回應中項目的索引
content_index	整數	內容部分索引

錯誤

error當發生錯誤時會回傳伺服器事件，錯誤可能是客戶端或伺服器問題。大多數錯誤是可復原的，且會話會持續開啟。

事件結構

{
  "type": "error",
  "error": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>",
    "event_id": "<event_id>"
  }
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `error`。
錯誤	物件	錯誤細節。請參閱下表中的巢狀性質。

錯誤性質

Field	類型	Description
型別	字串	錯誤的類型。例如，「invalid_request_error」和「server_error」是錯誤類型。
字碼	字串	如果有錯誤代碼。
訊息	字串	一個人類可讀的錯誤訊息。
param	字串	參數與錯誤相關，若有的話。
event_id	字串	造成錯誤的客戶端事件的 ID（如果適用）。

警告

warning當發生警告且不會中斷對話流程時，伺服器事件會被回傳。警告為資訊性提示，遊戲會照常進行。

事件結構

{
  "type": "warning",
  "warning": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>"
  }
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `warning`。
警告	物件	警告詳情。請參閱下表中的巢狀性質。

警示性質

Field	類型	Description
訊息	字串	一個人類可讀的警告訊息。
字碼	字串	Optional. 如果有警告代碼。
param	字串	Optional. 與警告相關的參數（如果有的話）。

input_audio_buffer.已清除

input_audio_buffer.cleared當客戶端以事件清除輸入音訊緩衝input_audio_buffer.clear區時，伺服器事件會被回傳。

事件結構

{
  "type": "input_audio_buffer.cleared"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `input_audio_buffer.cleared`。

input_audio_buffer.已提交

input_audio_buffer.committed當輸入音訊緩衝區被提交時，伺服器事件會回傳，無論是由用戶端或伺服器 VAD 模式自動提交。屬性 item_id 是使用者訊息項目的 ID。因此，事件 conversation.item.created 也會傳送給客戶端。

事件結構

{
  "type": "input_audio_buffer.committed",
  "previous_item_id": "<previous_item_id>",
  "item_id": "<item_id>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `input_audio_buffer.committed`。
前項目ID	字串	前一個項目的 ID，插入新項目後面。
item_id	字串	使用者訊息項目的 ID。

input_audio_buffer.speech_started

當音訊緩衝區偵測到語音時，伺服器 input_audio_buffer.speech_started 事件會以模式回傳 server_vad 。此事件可能在任何音訊加入緩衝區時發生（除非已偵測到語音）。

Note

用戶端可能想利用此事件中斷音訊播放或向使用者提供視覺回饋。

當語言停止時，客戶應該預期會接收 input_audio_buffer.speech_stopped 到一個事件。該 item_id 屬性是語音停止時所建立的使用者訊息項目的 ID。除非用戶端在 VAD 啟用時手動提交音訊緩衝區，否則 THE item_id 也會包含 input_audio_buffer.speech_stopped 在事件中。

事件結構

{
  "type": "input_audio_buffer.speech_started",
  "audio_start_ms": 0,
  "item_id": "<item_id>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `input_audio_buffer.speech_started`。
audio_start_ms	整數	從第一次偵測到語音時，所有寫入緩衝區的音訊開始起，都是毫秒。此特性對應於傳送到模型的音訊開始時間，因此包含 `prefix_padding_ms` 了會話中的配置。
item_id	字串	當語音停止時所產生的使用者訊息項目的 ID。

输入音频缓冲区.语音停止

input_audio_buffer.speech_stopped當伺服器偵測到音訊緩衝區中的語音結束時，該事件會以模式回傳server_vad。

伺服器也會傳送 conversation.item.created 一個包含由音訊緩衝區建立的使用者訊息項目的事件。

事件結構

{
  "type": "input_audio_buffer.speech_stopped",
  "audio_end_ms": 0,
  "item_id": "<item_id>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `input_audio_buffer.speech_stopped`。
audio_end_ms	整數	從會談開始到說話停止的幾毫秒。此屬性對應於傳送至模型的音訊結束，因此包含了會話中配置的 `min_silence_duration_ms` 。
item_id	字串	使用者訊息項目的 ID。

rate_limits.更新

伺服器 rate_limits.updated 事件會在回應開始時發出，以表示更新的速率限制。

當回應產生時，會保留部分標記給輸出標記。此處顯示的費率限制反映了該保留，並在回應完成後相應調整。

事件結構

{
  "type": "rate_limits.updated",
  "rate_limits": [
    {
      "name": "<name>",
      "limit": 0,
      "remaining": 0,
      "reset_seconds": 0
    }
  ]
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `rate_limits.updated`。
速率限制	RealtimeRateLimitsItem 陣列	費率限制資訊清單。

回應.audio.delta

response.audio.delta當模型產生的音訊更新時，伺服器事件會回傳。

事件結構

{
  "type": "response.audio.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.audio.delta`。
response_id	字串	回應的識別。
item_id	字串	項目的標識碼。
output_index	整數	回應中輸出項目的索引。
content_index	整數	項目內容陣列中內容部分的索引。
delta	字串	Base64編碼的音訊資料增量。

回應.audio.done

response.audio.done當模型產生的音訊完成時，伺服器事件會回傳。

當回應被中斷、不完整或取消時，此事件也會回傳。

事件結構

{
  "type": "response.audio.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.audio.done`。
response_id	字串	回應的識別。
item_id	字串	項目的標識碼。
output_index	整數	回應中輸出項目的索引。
content_index	整數	項目內容陣列中內容部分的索引。

response.audio_transcript.delta

response.audio_transcript.delta當模型產生的音訊輸出文字記錄更新時，伺服器事件會回傳。

事件結構

{
  "type": "response.audio_transcript.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.audio_transcript.delta`。
response_id	字串	回應的識別。
item_id	字串	項目的標識碼。
output_index	整數	回應中輸出項目的索引。
content_index	整數	項目內容陣列中內容部分的索引。
delta	字串	逐字稿delta。

response.audio_transcript.完成

response.audio_transcript.done當模型生成的音訊輸出進行串流時，伺服器事件會回傳。

當回應被中斷、不完整或取消時，此事件也會回傳。

事件結構

{
  "type": "response.audio_transcript.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "transcript": "<transcript>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.audio_transcript.done`。
response_id	字串	回應的識別。
item_id	字串	項目的標識碼。
output_index	整數	回應中輸出項目的索引。
content_index	整數	項目內容陣列中內容部分的索引。
文字記錄	字串	音頻的最終逐字稿。

response.function_call_arguments.delta

response.function_call_arguments.delta當模型產生的函式呼叫參數更新時，伺服器事件會被回傳。

事件結構

{
  "type": "response.function_call_arguments.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "call_id": "<call_id>",
  "delta": "<delta>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.function_call_arguments.delta`。
response_id	字串	回應的識別。
item_id	字串	函式呼叫項目的 ID。
output_index	整數	回應中輸出項目的索引。
call_id	字串	函式呼叫的 ID。
delta	字串	參數 delta 以 JSON 字串形式呈現。

response.function_call_arguments.完成

response.function_call_arguments.done當模型產生的函式呼叫參數串流完成時，伺服器事件會回傳。

當回應被中斷、不完整或取消時，此事件也會回傳。

事件結構

{
  "type": "response.function_call_arguments.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "call_id": "<call_id>",
  "arguments": "<arguments>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.function_call_arguments.done`。
response_id	字串	回應的識別。
item_id	字串	函式呼叫項目的 ID。
output_index	整數	回應中輸出項目的索引。
call_id	字串	函式呼叫的 ID。
arguments	字串	最後的參數會以 JSON 字串的形式呈現。

mcp_list_tools.in_progress（進行中）

mcp_list_tools.in_progress當服務開始從 MCP 伺服器列出可用工具時，伺服器事件會被回傳。

事件結構

{
  "type": "mcp_list_tools.in_progress",
  "item_id": "<mcp_list_tools_item_id>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `mcp_list_tools.in_progress`。
item_id	字串	MCP 清單工具項目的 ID。

mcp_list_tools。已完成

mcp_list_tools.completed當服務完成從 MCP 伺服器列出可用工具時，伺服器事件就會回傳。

事件結構

{
  "type": "mcp_list_tools.completed",
  "item_id": "<mcp_list_tools_item_id>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `mcp_list_tools.completed`。
item_id	字串	MCP 清單工具項目的 ID。

mcp_list_tools.失敗

當服務未能列出來自 MCP 伺服器的可用工具時，伺服器 mcp_list_tools.failed 事件會被回傳。

事件結構

{
  "type": "mcp_list_tools.failed",
  "item_id": "<mcp_list_tools_item_id>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `mcp_list_tools.failed`。
item_id	字串	MCP 清單工具項目的 ID。

response.mcp_call_arguments.delta

response.mcp_call_arguments.delta當模型產生的 MCP 工具呼叫參數更新時，伺服器事件會被回傳。

事件結構

{
  "type": "response.mcp_call_arguments.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "delta": "<delta>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.mcp_call_arguments.delta`。
response_id	字串	回應的識別。
item_id	字串	MCP 工具呼叫項目的 ID。
output_index	整數	回應中輸出項目的索引。
delta	字串	參數 delta 以 JSON 字串形式呈現。

response.mcp_call_arguments完成

response.mcp_call_arguments.done當模型產生的 MCP 工具呼叫參數串流完成時，伺服器事件會回傳。

事件結構

{
  "type": "response.mcp_call_arguments.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "arguments": "<arguments>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.mcp_call_arguments.done`。
response_id	字串	回應的識別。
item_id	字串	MCP 工具呼叫項目的 ID。
output_index	整數	回應中輸出項目的索引。
arguments	字串	最後的參數會以 JSON 字串的形式呈現。

response.mcp_call.in_progress（進行中）

response.mcp_call.in_progress當 MCP 工具呼叫開始處理時，伺服器事件會被回傳。

事件結構

{
  "type": "response.mcp_call.in_progress",
  "item_id": "<item_id>",
  "output_index": 0
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.mcp_call.in_progress`。
item_id	字串	MCP 工具呼叫項目的 ID。
output_index	整數	回應中輸出項目的索引。

response.mcp_call。完成

response.mcp_call.completed當 MCP 工具呼叫成功完成時，伺服器事件會回傳。

事件結構

{
  "type": "response.mcp_call.completed",
  "item_id": "<item_id>",
  "output_index": 0
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.mcp_call.completed`。
item_id	字串	MCP 工具呼叫項目的 ID。
output_index	整數	回應中輸出項目的索引。

response.mcp_call.失敗

response.mcp_call.failed當 MCP 工具呼叫失敗時，伺服器事件會被回傳。

事件結構

{
  "type": "response.mcp_call.failed",
  "item_id": "<item_id>",
  "output_index": 0
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.mcp_call.failed`。
item_id	字串	MCP 工具呼叫項目的 ID。
output_index	整數	回應中輸出項目的索引。

response.foundry_agent_call_arguments.delta

response.foundry_agent_call_arguments.delta當模型生成的 Foundry 代理呼叫參數更新時，伺服器事件會回傳。

事件結構

{
  "type": "response.foundry_agent_call_arguments.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "delta": "<delta>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.foundry_agent_call_arguments.delta`。
response_id	字串	回應的識別。
item_id	字串	代工廠代理的身份證件。
output_index	整數	回應中輸出項目的索引。
delta	字串	參數 delta 以 JSON 字串形式呈現。

response.foundry_agent_call_arguments。完成

response.foundry_agent_call_arguments.done當模型生成的 Foundry 代理呼叫參數串流完成時，伺服器事件會回傳。

事件結構

{
  "type": "response.foundry_agent_call_arguments.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "arguments": "<arguments>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.foundry_agent_call_arguments.done`。
response_id	字串	回應的識別。
item_id	字串	代工廠代理的身份證件。
output_index	整數	回應中輸出項目的索引。
arguments	字串	最後的參數會以 JSON 字串的形式呈現。

response.foundry_agent_call進行中

response.foundry_agent_call.in_progress當 Foundry agent 呼叫開始處理時，伺服器事件會被回傳。

事件結構

{
  "type": "response.foundry_agent_call.in_progress",
  "item_id": "<item_id>",
  "output_index": 0
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.foundry_agent_call.in_progress`。
item_id	字串	代工廠代理的身份證件。
agent_response_id	字串	鑄造廠代理的回應ID。
output_index	整數	回應中輸出項目的索引。

response.foundry_agent_call。已完成

當 Foundry agent 呼叫成功完成時，會回傳伺服器 response.foundry_agent_call.completed 事件。

事件結構

{
  "type": "response.foundry_agent_call.completed",
  "item_id": "<item_id>",
  "agent_response_id": "<agent_response_id>",
  "output_index": 0
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.foundry_agent_call.completed`。
item_id	字串	代工廠代理的身份證件。
output_index	整數	回應中輸出項目的索引。

response.foundry_agent_call.失敗

response.foundry_agent_call.failed當 Foundry agent 呼叫失敗時，伺服器事件會回傳。

事件結構

{
  "type": "response.foundry_agent_call.failed",
  "item_id": "<item_id>",
  "output_index": 0
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.foundry_agent_call.failed`。
item_id	字串	代工廠代理的身份證件。
output_index	整數	回應中輸出項目的索引。

response.output_item.新增

response.output_item.added當回應產生時產生新項目，伺服器事件會回傳。

事件結構

{
  "type": "response.output_item.added",
  "response_id": "<response_id>",
  "output_index": 0
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.output_item.added`。
response_id	字串	該項目所屬回應的識別碼。
output_index	整數	回應中輸出項目的索引。
項目	RealtimeConversationResponseItem	新增的那個項目。

response.output_item.已完成

response.output_item.done當項目完成串流時，伺服器事件會回傳。

當回應被中斷、不完整或取消時，此事件也會回傳。

事件結構

{
  "type": "response.output_item.done",
  "response_id": "<response_id>",
  "output_index": 0
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.output_item.done`。
response_id	字串	該項目所屬回應的識別碼。
output_index	整數	回應中輸出項目的索引。
項目	RealtimeConversationResponseItem	已經完成串流的項目。

response.text.delta

response.text.delta當模型生成的文字更新時，伺服器事件會被回傳。該文字對應 text 於助理訊息項目的內容部分。

事件結構

{
  "type": "response.text.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.text.delta`。
response_id	字串	回應的識別。
item_id	字串	項目的標識碼。
output_index	整數	回應中輸出項目的索引。
content_index	整數	項目內容陣列中內容部分的索引。
delta	字串	簡訊變速。

回應.text.done

response.text.done當模型產生的文字串流完成時，伺服器事件會回傳。該文字對應 text 於助理訊息項目的內容部分。

當回應被中斷、不完整或取消時，此事件也會回傳。

事件結構

{
  "type": "response.text.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "text": "<text>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.text.done`。
response_id	字串	回應的識別。
item_id	字串	項目的標識碼。
output_index	整數	回應中輸出項目的索引。
content_index	整數	項目內容陣列中內容部分的索引。
收發簡訊	字串	最終的文字內容。

session.avatar.switch_to_speaking

當化身轉換成說話狀態時，會回歸。利用此事件協調使用者介面變更，例如顯示語音指示器。

事件結構

{
  "type": "session.avatar.switch_to_speaking",
  "turn_id": "<turn_id>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `session.avatar.switch_to_speaking`。
turn_id	字串	Optional. 與化身狀態改變相關的回合ID。

session.avatar.switch_to_idle

當化身進入閒置狀態時會回歸。

事件結構

{
  "type": "session.avatar.switch_to_idle",
  "turn_id": "<turn_id>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `session.avatar.switch_to_idle`。
turn_id	字串	Optional. 與化身狀態改變相關的回合ID。

response.video.delta

當化身影片的影格資料串流到用戶端時，會回傳。幀有效載荷為base64編碼，並使用欄位 codec 指示的編解碼器。

事件結構

{
  "type": "response.video.delta",
  "output_index": 0,
  "codec": "h264",
  "delta": "<base64_encoded_video_frame>"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.video.delta`。
output_index	整數	回應中輸出項目的索引。
編解碼器	字串	用於影像資料的編解碼器（例如， `h264`）。
delta	字串	base64編碼的影片影格資料。

response.web_search_call.搜尋

當網頁搜尋工具呼叫進入搜尋狀態時，會回傳。

事件結構

{
  "type": "response.web_search_call.searching",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "sequence_number": 0
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.web_search_call.searching`。
response_id	字串	回應的識別。
item_id	字串	網路搜尋呼叫項目的 ID。
output_index	整數	回應中輸出項目的索引。
sequence_number	整數	網路搜尋呼叫的序號。

response.web_search_call進行中

當網頁搜尋工具呼叫進行時會回傳。

事件結構

{
  "type": "response.web_search_call.in_progress",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "sequence_number": 0
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.web_search_call.in_progress`。
response_id	字串	回應的識別。
item_id	字串	網路搜尋呼叫項目的 ID。
output_index	整數	回應中輸出項目的索引。
sequence_number	整數	網路搜尋呼叫的序號。

response.web_search_call。已完成

當網路搜尋工具呼叫完成後會回傳。

事件結構

{
  "type": "response.web_search_call.completed",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "sequence_number": 0
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.web_search_call.completed`。
response_id	字串	回應的識別。
item_id	字串	網路搜尋呼叫項目的 ID。
output_index	整數	回應中輸出項目的索引。
sequence_number	整數	網路搜尋呼叫的序號。

response.file_search_call.搜尋

當檔案搜尋工具呼叫進入搜尋狀態時，會回傳。

事件結構

{
  "type": "response.file_search_call.searching",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "sequence_number": 0
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.file_search_call.searching`。
response_id	字串	回應的識別。
item_id	字串	檔案搜尋呼叫項目的 ID。
output_index	整數	回應中輸出項目的索引。
sequence_number	整數	檔案搜尋呼叫的序號。

response.file_search_call.in_progress（進行中）

當檔案搜尋工具呼叫進行時會回傳。

事件結構

{
  "type": "response.file_search_call.in_progress",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "sequence_number": 0
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.file_search_call.in_progress`。
response_id	字串	回應的識別。
item_id	字串	檔案搜尋呼叫項目的 ID。
output_index	整數	回應中輸出項目的索引。
sequence_number	整數	檔案搜尋呼叫的序號。

response.file_search_call。完成

檔案搜尋工具呼叫完成後回傳。

事件結構

{
  "type": "response.file_search_call.completed",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "sequence_number": 0
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.file_search_call.completed`。
response_id	字串	回應的識別。
item_id	字串	檔案搜尋呼叫項目的 ID。
output_index	整數	回應中輸出項目的索引。
sequence_number	整數	檔案搜尋呼叫的序號。

output_audio_buffer 清除

當輸出音訊緩衝區因客戶端 output_audio_buffer.clear 事件被清除時，會回傳。在目前預覽中，這個事件只會在虛擬化身模式下觸發。

事件結構

{
  "type": "output_audio_buffer.cleared"
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `output_audio_buffer.cleared`。

response.audio_transcript.annotation.added

當註解（例如由網頁或檔案搜尋工具產生的引用）加入音頻逐字稿內容部分時，會回傳。

事件結構

{
  "type": "response.audio_transcript.annotation.added",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "annotation_index": 0,
  "annotation": {}
}

屬性

Field	類型	Description
型別	字串	事件類型必須為 `response.audio_transcript.annotation.added`。
response_id	字串	回應的識別。
item_id	字串	項目的標識碼。
output_index	整數	回應中輸出項目的索引。
content_index	整數	項目內容陣列中內容部分的索引。
annotation_index	整數	註解的索引。
註釋	物件	註解物件。該結構依註解來源而異（例如，網路搜尋引用）。

元件

音訊格式

RealtimeAudioFormat

輸入音訊所用的基本音訊格式。

允許的數值：

pcm16 - 16 位元 PCM 音訊格式
g711_ulaw - G.711 μ律音訊格式
g711_alaw - G.711 A-law 音訊格式

RealtimeOutputAudioFormat

用於特定取樣率輸出音訊的音訊格式。

允許的數值：

pcm16 - 預設取樣率（24kHz）下的16位元PCM音訊格式
pcm16_8000hz - 16位元 PCM 音訊格式，採樣率為 8kHz
pcm16_16000hz - 16位元PCM音訊格式，取樣率為16kHz
g711_ulaw - G.711 μ律（mu-law）音訊格式，取樣率為8kHz
g711_alaw - G.711 A-law 音訊格式，採樣率為 8kHz

即時音訊輸入轉錄設定

輸入音訊轉譯的組態。

Field	類型	Description
型號	字串	轉錄模型。支援有 `gpt-realtime` 和 `gpt-realtime-mini`： `whisper-1`，`gpt-4o-transcribe`，`gpt-4o-mini-transcribe`，`gpt-4o-transcribe-diarize`，`mai-transcribe`。與其他所有模型與代理均支援： `azure-speech` 及 `mai-transcribe`
語言	字串	可選語言代碼如 BCP-47（例如 `en-US`）、ISO-639-1（例如 `en`）、或具自動偵測功能的多語言（例如 `en,zh`）。建議使用此設定，請參見Azure語音轉文字支援語言。
custom_speech	物件	自訂語音模型的可選配置，僅適用於 `azure-speech` 模型。
phrase_list	string[]	可選的短語清單提示偏見識別，僅適用於 `azure-speech` 模型。
提示	字串	可選的提示文字用於引導轉錄，僅適用於 `whisper-1`、 `gpt-4o-transcribe`和 `gpt-4o-mini-transcribegpt-4o-transcribe-diarize` 模型。

RealtimeInputAudioNoiseReductionSettings

這可以是：

一個即時OpenAINoiseReduction 物件
一個 RealtimeAzureDeepNoiseSuppression 物件

RealtimeOpenAINoiseReduction

OpenAI 的降噪配置，具備明確的類型欄位，僅適用於 gpt-realtime 和 gpt-realtime-mini 模型。

Field	類型	Description
型別	字串	`near_field` 或 `far_field`

RealtimeAzureDeepNoiseSuppression

輸入音訊雜訊減少的設定。

Field	類型	Description
型別	字串	必須是 `"azure_deep_noise_suppression"`

RealtimeInputAudioEchoCancellationSettings

伺服器端音訊處理的回聲消除配置。

Field	類型	Description
型別	字串	必須是 `"server_echo_cancellation"`

語音配置

RealtimeVoice

所有支援語音配置的合併。

這可以是：

一個 RealtimeOpenAIVoice 物件
一個 RealtimeAzureVoice 物件

RealtimeOpenAI遊戲

OpenAI 語音設定，帶有明確的類型欄位。

Field	類型	Description
型別	字串	必須是 `"openai"`
名字	字串	OpenAI 語音名稱：，，， `alloyashballadcoralechosageshimmerversemarincedar`

RealtimeAzure語音

Azure 語音配置基礎。這是一個有不同類型的歧視聯盟：

RealtimeAzureStandardVoice

Azure 標準語音配置。

Field	類型	Description
型別	字串	必須是 `"azure-standard"`
名字	字串	語音名稱（不能空）
溫度	編號	Optional. 溫度介於0.0到1.0之間
custom_lexicon_url	字串	Optional. 自訂詞彙的網址
custom_text_normalization_url	字串	Optional. 自訂文字正規化的網址
prefer_locales	string[]	Optional. 偏好的地區設定偏好地點會改變語言的口音。如果值未設定，TTS 會使用每種語言的預設重音符號。例如，當 TTS 講英語時，它會使用美式英語口音。說西班牙語時，它會用墨西哥西班牙口音。若將prefer_locales設為 `["en-GB", "es-ES"]`，英語口音為英式英語，西班牙語口音為歐洲西班牙語。而且 TTS 也能說法語、中文等其他語言。
地區設定	字串	Optional. 地區設定規格強制執行 TTS 輸出的地點。若未設定，TTS 會使用指定地點進行語音。例如，將locale設為 `en-US`，TTS 總是使用美式英語口音來講文字內容，即使文字內容是另一種語言。如果文字內容是中文，TTS 會輸出靜音。
樣式	字串	Optional. 語音風格
音高	字串	Optional. 聲音輸出的音高調整。遵循與 `pitch` SSML `prosody` 元素屬性相同的規則（參見調整韻律）。典型值：命名的電平（，，，，，）、`x-low`相對變化（例如 `low`， `medium`， `high`， `x-high`）或絕對頻率（例如 `default`）。 `+10%-5%+50Hz-2st200Hz`
利率	字串	Optional. 語音輸出的語音速率調整。遵循與 `rate` SSML `prosody` 元素屬性相同的規則（參見調整韻律）。典型值：命名等級（`x-slow`，， `slowmedium`， `fast`， `x-fast`，）、`default`相對百分比（例如 `+20%`、 `-10%`），或非負乘數（例如 `0.5`， `1.5`）。
volume	字串	Optional. 語音輸出的音量調整。遵循與 `volume` SSML `prosody` 元素屬性相同的規則（參見調整韻律）。典型值：命名等級（`silent`，， `x-softsoft`， `mediumloud`， `x-loud`，，）、`default`0.0 到 100.0 的絕對數，或相對變化（例如 `+10`， `-6dB`）。

RealtimeAzureCustomVoice

Azure 自訂語音設定（偏好用於自訂語音）。

Field	類型	Description
型別	字串	必須是 `"azure-custom"`
名字	字串	語音名稱（不能空）
endpoint_id	字串	端點 ID（不能空）
溫度	編號	Optional. 溫度介於0.0到1.0之間
custom_lexicon_url	字串	Optional. 自訂詞彙的網址
custom_text_normalization_url	字串	Optional. 自訂文字正規化的網址
prefer_locales	string[]	Optional. 偏好的地區設定偏好地點會改變語言的口音。如果值未設定，TTS 會使用每種語言的預設重音符號。例如，當 TTS 講英語時，它會使用美式英語口音。說西班牙語時，它會用墨西哥西班牙口音。若將prefer_locales設為 `["en-GB", "es-ES"]`，英語口音為英式英語，西班牙語口音為歐洲西班牙語。而且 TTS 也能說法語、中文等其他語言。
地區設定	字串	Optional. 地區設定規格強制執行 TTS 輸出的地點。若未設定，TTS 會使用指定地點進行語音。例如，將locale設為 `en-US`，TTS 總是使用美式英語口音來講文字內容，即使文字內容是另一種語言。如果文字內容是中文，TTS 會輸出靜音。
樣式	字串	Optional. 語音風格
音高	字串	Optional. 聲音輸出的音高調整。遵循與 `pitch` SSML `prosody` 元素屬性相同的規則（參見調整韻律）。典型值：命名的電平（，，，，，）、`x-low`相對變化（例如 `low`， `medium`， `high`， `x-high`）或絕對頻率（例如 `default`）。 `+10%-5%+50Hz-2st200Hz`
利率	字串	Optional. 語音輸出的語音速率調整。遵循與 `rate` SSML `prosody` 元素屬性相同的規則（參見調整韻律）。典型值：命名等級（`x-slow`，， `slowmedium`， `fast`， `x-fast`，）、`default`相對百分比（例如 `+20%`、 `-10%`），或非負乘數（例如 `0.5`， `1.5`）。
volume	字串	Optional. 語音輸出的音量調整。遵循與 `volume` SSML `prosody` 元素屬性相同的規則（參見調整韻律）。典型值：命名等級（`silent`，， `x-softsoft`， `mediumloud`， `x-loud`，，）、`default`0.0 到 100.0 的絕對數，或相對變化（例如 `+10`， `-6dB`）。

範例：

{
  "type": "azure-custom",
  "name": "my-custom-voice",
  "endpoint_id": "12345678-1234-1234-1234-123456789012",
  "temperature": 0.7,
  "style": "cheerful",
  "locale": "en-US"
}

RealtimeAzurePersonalVoice

Azure 個人語音設定。

Field	類型	Description
型別	字串	必須是 `"azure-personal"`
名字	字串	語音名稱（不能空）
溫度	編號	Optional. 溫度介於0.0到1.0之間
型號	字串	基礎模型： `DragonLatestNeural`， `DragonHDOmniLatestNeural`， `MAI-Voice-1`
custom_lexicon_url	字串	Optional. 自訂詞彙的網址
custom_text_normalization_url	字串	Optional. 自訂文字正規化的網址
prefer_locales	string[]	Optional. 偏好的地區設定偏好地點會改變語言的口音。如果值未設定，TTS 會使用每種語言的預設重音符號。例如，當 TTS 講英語時，它會使用美式英語口音。說西班牙語時，它會用墨西哥西班牙口音。若將prefer_locales設為 `["en-GB", "es-ES"]`，英語口音為英式英語，西班牙語口音為歐洲西班牙語。而且 TTS 也能說法語、中文等其他語言。
地區設定	字串	Optional. 地區設定規格強制執行 TTS 輸出的地點。若未設定，TTS 會使用指定地點進行語音。例如，將locale設為 `en-US`，TTS 總是使用美式英語口音來講文字內容，即使文字內容是另一種語言。如果文字內容是中文，TTS 會輸出靜音。
音高	字串	Optional. 聲音輸出的音高調整。遵循與 `pitch` SSML `prosody` 元素屬性相同的規則（參見調整韻律）。典型值：命名的電平（，，，，，）、`x-low`相對變化（例如 `low`， `medium`， `high`， `x-high`）或絕對頻率（例如 `default`）。 `+10%-5%+50Hz-2st200Hz`
利率	字串	Optional. 語音輸出的語音速率調整。遵循與 `rate` SSML `prosody` 元素屬性相同的規則（參見調整韻律）。典型值：命名等級（`x-slow`，， `slowmedium`， `fast`， `x-fast`，）、`default`相對百分比（例如 `+20%`、 `-10%`），或非負乘數（例如 `0.5`， `1.5`）。
volume	字串	Optional. 語音輸出的音量調整。遵循與 `volume` SSML `prosody` 元素屬性相同的規則（參見調整韻律）。典型值：命名等級（`silent`，， `x-softsoft`， `mediumloud`， `x-loud`，，）、`default`0.0 到 100.0 的絕對數，或相對變化（例如 `+10`， `-6dB`）。

轉彎偵測

即時轉向偵測

回合偵測的設定。這是一個支持多種VAD類型、受歧視的工會。

RealtimeServerVAD

基礎基於VAD的轉彎偵測。

Field	類型	Description
型別	字串	必須是 `"server_vad"`
閾值	float	Optional. 啟動門檻（0.0-1.0）（預設：0.5）
prefix_padding_ms	整數	Optional. 語音開始前的音訊填充（預設：400）
silence_duration_ms	整數	Optional. 靜音持續時間以偵測語音結束（預設：500）
speech_duration_ms	整數	Optional. 最低語音持續時間（預設：200）
end_of_utterance_detection	實時EOU接收	Optional. 語句結束偵測設定
create_response	布林值	Optional. 啟用或停用是否產生回應（預設：true）。
interrupt_response	布林值	Optional. 啟用或停用突入中斷（預設：true）。
auto_truncate	布林值	Optional. 中斷時自動截斷（預設：false）

RealtimeOpenAISemanticVAD

OpenAI 語意式 VAD 配置，利用模型判斷使用者何時講完話。僅限於和 gpt-realtime 型號。gpt-realtime-mini

Field	類型	Description
型別	字串	必須是 `"semantic_vad"`
eagerness	字串	Optional. 這是一種調整最大等待時間的方法，用於控制模型打斷使用者的急切程度。在轉錄模式下，即使模型沒有回覆，它也會影響音訊的分段方式。允許下列值： - `auto` （預設）等同於 `medium`， - `low` 讓使用者慢慢說話， - `high` 將盡快對音訊進行分塊。如果您想要模型在交談模式中更頻繁地回應，或在轉譯模式中更快地傳回轉錄事件，您可以將急切性設定為 `high`。另一方面，如果您想要讓使用者在交談模式中不間斷地說話，或者如果您想要在轉錄模式中取得較大的文字記錄區塊，您可以將渴望設定為 `low`。
create_response	布林值	Optional. 啟用或停用是否產生回應（預設：true）。
interrupt_response	布林值	Optional. 啟用或停用突入中斷（預設：true）。

RealtimeAzureSemanticVAD

Azure 語意 VAD，該系統決定使用者何時開始並使用語意語音模型發言，在嘈雜環境中提供更穩健的偵測能力。

Field	類型	Description
型別	字串	必須是 `"azure_semantic_vad"`
閾值	float	Optional. 啟動門檻（預設：0.5）
prefix_padding_ms	整數	Optional. 語音前的音訊填充（預設：420）
silence_duration_ms	整數	Optional. 語音結束的靜默持續時間（預設：500）
end_of_utterance_detection	實時EOU接收	Optional. EOU 偵測設定
speech_duration_ms	整數	Optional. 最低語音時長（預設：80）
remove_filler_words	布林值	Optional. 移除填充詞（預設：false）
語言	string[]	Optional. 支持英語。其他語言則被忽略（預設：無）。
create_response	布林值	Optional. 啟用或停用是否產生回應（預設：true）。
interrupt_response	布林值	Optional. 啟用或停用突入中斷（預設：true）。
auto_truncate	布林值	Optional. 中斷時自動截斷（預設：false）

RealtimeAzureSemanticVADMultilingual

Azure semantic VAD （default variant）.

Field	類型	Description
型別	字串	必須是 `"azure_semantic_vad_multilingual"`
閾值	float	Optional. 啟動門檻（預設：0.5）
prefix_padding_ms	整數	Optional. 語音前的音訊填充（預設：420）
silence_duration_ms	整數	Optional. 語音結束的靜默持續時間（預設：500）
end_of_utterance_detection	實時EOU接收	Optional. EOU 偵測設定
speech_duration_ms	整數	Optional. 最低語音時長（預設：80）
remove_filler_words	布林值	Optional. 移除填充詞（預設：false）
語言	string[]	Optional. 支援英語、西班牙語、法語、義大利語、德語（德國）、日語、葡萄牙語、中文、韓語、印地語。其他語言則被忽略（預設：無）。
create_response	布林值	Optional. 啟用或停用是否產生回應（預設：true）。
interrupt_response	布林值	Optional. 啟用或停用突入中斷（預設：true）。
auto_truncate	布林值	Optional. 中斷時自動截斷（預設：false）

實時EOU接收

Azure 語尾（EOU）可指示終端使用者何時停止說話，同時允許自然停頓。結束語句偵測可以大幅減少過早的回合結束訊號，而不需要新增使用者感知的延遲。

Field	類型	Description
型號	字串	可以支援 `semantic_detection_v1` 英語，或 `semantic_detection_v1_multilingual` 支援英語、西班牙語、法語、義大利語、德語（DE）、日語、葡萄牙語、中文、韓語、印地語
threshold_level	字串	Optional. 偵測閾值等級（`low`、 `medium`、 `highdefault`和），預設值等於 `medium` 設定。設定越低，刑期完成的機率就越高。
timeout_ms	編號	Optional. 等待更多用戶語音的時間，以毫秒計。預設為 1000 毫秒。

頭像配置

RealtimeAvatarConfig

虛擬化身串流與行為設定。

Field	類型	Description
型別	字串	Optional. 阿凡達類型。允許的值： `video-avatar`、 `photo-avatar`。預設為 `video-avatar`
ice_servers	實時冰服務器[]	Optional. WebRTC 的 ICE 伺服器
字元	字串	角色名稱或虛擬角色識別碼
樣式	字串	Optional. 阿凡達風格（情感語氣，說話風格）
定製	布林值	頭像是否是客製化的
型號	字串	Optional. 照片頭像的基礎模型名稱，若類型為 `photo-avatar`，則必須，有效值為 `vasa-1`
影片	RealtimeVideoParams	Optional. 視訊設定
場景	即時化身場景	Optional. 虛擬化身在影片畫面中的縮放等級、位置、旋轉與移動幅度設定
output_protocol	字串	Optional. 虛擬化身串流的輸出協定。允許的值： `websocket` 和 `webrtc`。預設為 `webrtc`
output_audit_audio	布林值	Optional. 啟用時，即使虛擬化身輸出是透過 WebRTC 傳送，也能透過 WebSocket 轉發審核音訊以供審查/除錯。預設為 `false`

實時冰服務器

用於 WebRTC 連線協商的 ICE 伺服器設定。

Field	類型	Description
網址	string[]	ICE 伺服器網址（TURN 或 STUN 端點）
使用者名稱	字串	Optional. 認證用的用戶名
認證	字串	Optional. 認證憑證

RealtimeVideoParams

avatar 的影片串流參數。

Field	類型	Description
位元速率	整數	Optional. 位元率（以位元每秒計）（預設：2000000）
編解碼器	字串	Optional. 視訊編碼，目前僅有 `h264` （預設： `h264`）
裁切	即時影片裁剪	Optional. 裁切設定
解析	即時視訊解析度	Optional. 解析度設定
背景	即時影像背景	Optional. 背景設定
gop_size	整數	Optional. 圖片群組大小（預設：10，範圍：1–2000）

即時影片裁剪

影片裁切矩形定義。

Field	類型	Description
top_left	整數[]	左上角 [x， y]，非負整數
bottom_right	整數[]	右下角 [x， y]，非負整數

即時視訊解析度

影片解析度規格。

Field	類型	Description
width	整數	寬度（像素為單位）（必須是 > 0）
height	整數	高度（像素數）必須為 > 0

即時影像背景

影片背景設定。只能設定一個 image_url 或 color 。

Field	類型	Description
image_url	字串	Optional. 背景圖片的網址
色彩	字串	Optional. 背景色值

即時化身場景

設定化身在影片畫面中的縮放等級、位置、旋轉及移動幅度。

Field	類型	Description
兩指縮放	編號	Optional. 虛擬形象的縮放等級。範圍為（0， +∞）。值小於1時縮放，值大於1時放大。預設值為 0
position_x	編號	Optional. 化身的水平位置。距離為 [-1， 1]，作為畫面寬度的比例。負值向左移動，正值向右移動。預設值為 0
position_y	編號	Optional. 虛擬形象的垂直位置。射程為 [-1， 1]，即幀高的比例。負值會往上，正值會往下。預設值為 0
rotation_x	編號	Optional. 繞 X 軸旋轉（俯仰角）。範圍為弧度為[-π， π]。負值會往上旋轉，正值會向下旋轉。預設值為 0
rotation_y	編號	Optional. 繞Y軸旋轉（偏航）。範圍為弧度為[-π， π]。負值向左旋轉，正值向右旋轉。預設值為 0
rotation_z	編號	Optional. 繞Z軸旋轉（滾轉）。範圍為弧度為[-π， π]。負值逆時針旋轉，正值順時針旋轉。預設值為 0
振幅	編號	Optional. 阿凡達移動的幅度。範圍為（0， 1）。（0， 1）中的值代表減振幅，1 表示全振幅。預設值為 0

動畫組態

即時動畫

動畫輸出的配置，包括混合形狀與維素。

Field	類型	Description
model_name	字串	Optional. 動畫模型名稱（預設： `"default"`）
outputs	RealtimeAnimationOutputType[]	Optional. 輸出類型（預設： `["blendshapes"]`）

RealtimeAnimationOutputType

要輸出的動畫資料類型。

允許的數值：

blendshapes - 臉部混合形狀資料
viseme_id - Viseme 識別碼資料

會話設定

RealtimeRequestSession

事件中使用 session.update 的會話設定物件。

Field	類型	Description
型號	字串	Optional. 型號名稱可使用。
模態	RealtimeModality[]	Optional. 支援的會話輸出模式。例如，「模態」：[“text”、“audio”] 是預設設定，能同時啟用文字與音訊輸出模態。若要啟用僅有文字輸出，請設定「modalities」：[“text”]。要啟用頭像輸出，請設定「模態」：[“text”、“audio”、“avatar”]。你不能只啟用音訊。
動畫	即時動畫	Optional. 動畫設定
語音	RealtimeVoice	Optional. 語音設定
instructions	字串	Optional. 型號的系統說明書。如果使用 OpenAI 語音，這些說明可能會指導輸出音訊，但不一定適用於 Azure 語音。
input_audio_sampling_rate	整數	Optional. 輸入音訊取樣率以 Hz（預設：24000 表示`pcm16`，和 `g711_ulaw`8000 ）`g711_alaw`
input_audio_format	RealtimeAudioFormat	Optional. 輸入音訊格式（預設： `pcm16`）
output_audio_format	RealtimeOutputAudioFormat	Optional. 輸出音訊格式（預設： `pcm16`）
input_audio_noise_reduction	RealtimeInputAudioNoiseReductionSettings	輸入音訊雜訊減少的設定。這可以設定為 null 以關閉。雜訊減少會先篩選新增至輸入音訊緩衝區的音訊，再將其傳送至 VAD 和模型。篩選音訊可以改善 VAD 和回合偵測精確度（減少誤判）和模型效能，方法是改善對輸入音訊的感知。此性質是可作廢的。
input_audio_echo_cancellation	RealtimeInputAudioEchoCancellationSettings	輸入音訊回聲消除的配置。這可以設定為 null 以關閉。這種服務端的回聲消除功能能透過減少回聲和混響的影響，幫助提升輸入音訊的品質。此性質是可作廢的。
input_audio_transcription	即時音頻輸入轉錄設置	輸入音訊轉譯的組態。根據預設，組態為 null（關閉）。輸入音訊轉譯不是模型的原生，因為模型會直接取用音訊。轉錄會透過 `/audio/transcriptions` 端點以異步方式執行，而且應視為關於輸入音訊內容的指引，而非模型所精確聽到的內容。如需轉譯服務的其他指引，用戶端可以選擇性地設定語言並提示轉譯。此性質是可作廢的。
turn_detection	RealtimeTurnDetection	是該場次的轉彎偵測設定。這可以設定為 null 以關閉。
工具	RealtimeTool 陣列	模型在該場次可用的工具。
tool_choice	RealtimeToolChoice	本次會話的工具選擇。允許的值：`auto`、、 `nonerequired`和。否則，你可以指定要使用的函式名稱。
溫度	編號	模型的取樣溫度。允許的溫度值限制在 [0.6， 1.2]。預設為 0.8。
max_response_output_tokens	整數或「inf」	每個助理回應的最大輸出標記數，包含工具呼叫次數。指定一個介於 1 到 4096 之間的整數以限制輸出代幣。否則，將值設為「inf」以允許最大數量的標記。例如，若要限制輸出標記數為 1000，則設 `"max_response_output_tokens": 1000`。為了允許最大數量的標記，請設定 `"max_response_output_tokens": "inf"`。預設為 `"inf"`。
臨時應對	InterimResponseConfig	Optional. 在延遲或工具呼叫期間產生臨時回應的配置。
推理努力	ReasoningEffort	Optional. 限制推理模型的推理工作。詳情請參考 Azure Foundry doc。減少推理工作可能會導致回應更快，以及回應中用於推理的權杖較少。
頭像	RealtimeAvatarConfig	Optional. 虛擬人偶設定
output_audio_timestamp_types	RealtimeAudioTimestamp類型[]	Optional. 輸出音訊的時間戳記類型
中繼資料	地圖	Optional. 最多可設定 16 對鍵值對，可附加於會話。這對於以結構化格式儲存有關會話的額外資訊非常有用，例如追蹤 ID、使用者上下文或應用程式專屬標籤。這些鍵值對也包含在 Microsoft Foundry 資源日誌中，用於追蹤與診斷。鍵長最多可為 64 個字元，數值最多可達 512 個字元。

RealtimeModality

支援會話輸出模式。

允許的數值：

text - 文字輸出
audio - 音訊輸出
animation - 動畫輸出
avatar - Avatar 影片輸出

RealtimeAudioTimestampType

音訊回應內容支援的輸出時間戳記類型。

允許的數值：

word - 輸出音訊中每個字的時間戳記

ReasoningEffort

限制推理模型的推理工作。請查閱模型文件中每個模型的支援數值。減少推理工作可能會導致回應更快，以及回應中用於推理的權杖較少。

允許的數值：

none - 不需推理努力
minimal - 推理努力最小
low - 低推理努力 - 以較少推理方式快速回應
medium - 中等推理努力——在速度與推理深度之間取得平衡
high - 高推理努力——推理更為深入，可能需要更長時間
xhigh - 超高推理努力 - 最大推理深度

工具配置

我們支援兩種工具：函式呼叫和允許你連接 MCP 伺服器的 MCP 工具。

RealtimeTool

函式調用工具定義。

Field	類型	Description
型別	字串	必須是 `"function"`
名字	字串	函式名稱
描述	字串	功能描述與使用指引
parameters	物件	函式參數作為 JSON schema 物件

RealtimeToolChoice

工具選擇策略。

這可以是：

"auto" - 讓模型選擇
"none" - 不要用工具
"required" - 必須使用工具
{ "type": "function", "name": "function_name" } - 使用特定功能

MCPTool

MCP 工具配置。

Field	類型	Description
型別	字串	必須是 `"mcp"`
伺服器標籤	字串	Required. MCP 伺服器的標籤。
伺服器_URL	字串	Required. MCP 伺服器的網址。
允許的工具	string[]	Optional. 允許使用工具名稱的清單。若未特別說明，所有工具皆可使用。
headers	物件	Optional. MCP 請求中還需包含額外的標頭。
授權	字串	Optional. MCP 請求的授權令牌。
需核准	字串或字典	Optional. 若設定為字串，值必須為 `never` 或 `always`。若設定為字典，格式必須為 `{"never": ["<tool_name_1>", "<tool_name_2>"], "always": ["<tool_name_3>"]}`。預設值為 `always`。當設為 `always`時，工具執行需要核准，當 MCP 參數完成時會 mcp_approval_request 送給客戶端，且只有在收到 mcp_approval_response 時 `approve=true` 才會執行。當設定為 `never`時，工具將自動執行，無需經過批准。

FoundryAgentTool

整合 Foundry 代理作為工具的工具定義。這促成了聊天監督模式，即時聊天代理處理基本互動，並將複雜任務委派給更智慧的 Foundry 代理。

Field	類型	Description
型別	字串	必須是 `"foundry_agent"`
agent_name	字串	Required. 要聯絡的鑄造廠代理人的名字。
agent_version	字串	Optional. 那個要聯絡的鑄造廠特工版本。
project_name	字串	Required. 包含該代理人的鑄造廠專案名稱。
client_id (客戶識別碼)	字串	Optional. 與Foundry代理人相關的客戶ID。
描述	字串	Optional. Foundry 代理工具的可選描述。如果提供，它會用來取代 Foundry 入口中的代理人描述。
foundry_resource_override	字串	Optional. 覆蓋用於執行代理人的 Foundry 資源。
agent_context_type	字串	Optional. 呼叫 Foundry 代理時應使用的上下文類型。可能的值： `no_context`， `agent_context`。預設值為 `agent_context`。 `no_context`：僅傳送當前使用者輸入，不維護上下文。 `agent_context`：代理會維護自己的上下文（執行緒），每呼叫僅發送當前輸入。
return_agent_response_directly	布林值	Optional. 是否直接在語音即時回應中回傳客服人員的回應。預設值為 `true`。當設定為 `false`時，回應會送給聊天代理進行重新表述。

範例：

{
  "instructions": "You are a helpful assistant. Please respond with a short message like 'working on this' before calling the agent tool.",
  "tools": [
    {
      "type": "foundry_agent",
      "agent_name": "customer-service-agent",
      "agent_version": "2",
      "project_name": "my-foundry-project",
      "description": "A helpful agent that can search online information and handle complex customer requests"
    }
  ]
}

臨時應變配置

臨時回應讓系統在工具執行時能產生佔位語音回應，避免靜默，提升使用者體驗。

InterimResponseConfig

臨時回應產生的配置。這是一種聯合類型，可以是以下其中一種：

StaticInterimResponseConfig - 從預設清單中選擇的預先產生的臨時回應。
LlmInterimResponseConfig - LLM 產生的臨時回應。

StaticInterimResponseConfig

靜態臨時回應產生的配置。當符合任何觸發條件時，會隨機從已設定的文字中選擇。

Field	類型	Description
型別	字串	必須是 `"static-interim-response"`。
triggers	臨時反應觸發[]	Optional. 可能觸發臨時回應的觸發條件清單。任何觸發點都可以啟動臨時反應（或邏輯）。支援的值：`latency`、`tool`。預設值為 `["latency"]`。
latency_threshold_ms	整數	Optional. 延遲閾值在觸發中間反應前的毫秒。預設是 2000ms。最低值為 0。
文本	string[]	Optional. 隨機選擇的臨時回應文字選項列表。

範例：

{
  "session": {
    "interim-response": {
      "type": "static-interim-response",
      "triggers": ["latency", "tool"],
      "latency_threshold_ms": 1500,
      "texts": [
        "Let me think about that...",
        "One moment please...",
        "Working on that for you..."
      ]
    }
  }
}

LlmInterimResponseConfig

基於 LLM 的中期響應產生設定。利用大型語言模型（LLM）在滿足任何觸發條件時產生情境感知的中間回應。

Field	類型	Description
型別	字串	必須是 `"llm-interim-response"`。
triggers	臨時反應觸發[]	Optional. 可能觸發臨時回應的觸發條件清單。任何觸發點都可以啟動臨時反應（或邏輯）。支援的值：`latency`、`tool`。預設值為 `["latency"]`。
latency_threshold_ms	整數	Optional. 延遲閾值在觸發中間反應前的毫秒。預設是 2000ms。最低值為 0。
型號	字串	Optional. 用於基於大型語言模型（LLM）的中期回應產生模型。預設值為 `gpt-4.1-mini`。預設模式可能會在沒有新 API 版本的情況下改變。
instructions	字串	Optional. 自訂指令以產生臨時回應。若未提供，則使用預設提示。
max_completion_tokens	整數	Optional. 為中期回應產生的最大代幣數量。預設值為 50。最小值為 1。

範例：

{
  "session": {
    "interim-response": {
      "type": "llm-interim-response",
      "triggers": ["tool"],
      "latency_threshold_ms": 2000,
      "model": "gpt-4.1-mini",
      "instructions": "Generate a brief, friendly acknowledgment that you're working on the user's request.",
      "max_completion_tokens": 30
    }
  }
}

臨時反應觸發器

能啟動中期反應產生的觸發點。

允許的數值：

latency - 當響應延遲超過閾值時觸發臨時回應
tool - 在執行工具呼叫時觸發臨時回應

RealtimeConversationResponseItem

這是一種聯合類型，可以是以下其中一種：

RealtimeConversationUserMessageItem

使用者訊息項目。

Field	類型	Description
id	字串	物品的唯一ID。
型別	字串	必須是 `"message"`
物件	字串	必須是 `"conversation.item"`
角色	字串	必須是 `"user"`
內容	即時輸入文字內容部分	訊息的內容。
狀態	RealtimeItemStatus	項目的狀態。

RealtimeConversationAssistant訊息項目

助理訊息項目。

Field	類型	Description
id	字串	物品的唯一ID。
型別	字串	必須是 `"message"`
物件	字串	必須是 `"conversation.item"`
角色	字串	必須是 `"assistant"`
內容	RealtimeOutputTextContentPart[] 或 RealtimeOutputAudioContentPart[]	訊息的內容。
狀態	RealtimeItemStatus	項目的狀態。

RealtimeConversationSystemMessageItem

系統訊息項目。

Field	類型	Description
id	字串	物品的唯一ID。
型別	字串	必須是 `"message"`
物件	字串	必須是 `"conversation.item"`
角色	字串	必須是 `"system"`
內容	RealtimeInputTextContentPart[]	訊息的內容。
狀態	RealtimeItemStatus	項目的狀態。

RealtimeConversationFunctionCallItem

函式呼叫請求項目。

Field	類型	Description
id	字串	物品的唯一ID。
型別	字串	必須是 `"function_call"`
物件	字串	必須是 `"conversation.item"`
名字	字串	要呼叫的函式名稱。
arguments	字串	函式呼叫的參數是 JSON 字串。
call_id	字串	函式呼叫的唯一 ID。
狀態	RealtimeItemStatus	項目的狀態。

RealtimeConversationFunctionCallOutputItem

函式呼叫回應項目。

Field	類型	Description
id	字串	物品的唯一ID。
型別	字串	必須是 `"function_call_output"`
物件	字串	必須是 `"conversation.item"`
名字	字串	被呼叫的函式名稱。
輸出	字串	函式呼叫的輸出。
call_id	字串	函式呼叫的唯一 ID。
狀態	RealtimeItemStatus	項目的狀態。

即時對話MCPList工具項目

MCP 清單工具回應項目。

Field	類型	Description
id	字串	物品的唯一ID。
型別	字串	必須是 `"mcp_list_tools"`
伺服器標籤	字串	MCP 伺服器的標籤。

即時對話MCPCall項目

MCP 來電回應項目。

Field	類型	Description
id	字串	物品的唯一ID。
型別	字串	必須是 `"mcp_call"`
伺服器標籤	字串	MCP 伺服器的標籤。
名字	字串	要呼叫的工具名稱。
approval_request_id	字串	MCP 通話的核准申請 ID。
arguments	字串	MCP呼籲的論點。
輸出	字串	MCP 呼叫的輸出。
錯誤	物件	錯誤說明 MCP 呼叫是否失敗。

即時對話MCPApproval請求項目

MCP 核准申請項目。

Field	類型	Description
id	字串	物品的唯一ID。
型別	字串	必須是 `"mcp_approval_request"`
伺服器標籤	字串	MCP 伺服器的標籤。
名字	字串	要呼叫的工具名稱。
arguments	字串	MCP呼籲的論點。

即時對話FoundryAgentCallItem。

鑄造廠代理來電回應項目。

Field	類型	Description
id	字串	物品的唯一ID。
型別	字串	必須是 `"foundry_agent_call"`
名字	字串	鑄造廠代理人的名字。
call_id	字串	通話的ID。
arguments	字串	關於鑄造廠代理人來電的論點。
agent_response_id	字串	Optional. 鑄造廠代理的回應ID。
輸出	字串	Optional. 代工廠代理通話的輸出。
錯誤	物件	Optional. 錯誤是說明代工廠代理呼叫失敗的情況。

即時對話網路搜尋呼叫項目

網路搜尋呼叫回應項目。

Field	類型	Description
id	字串	網路搜尋工具呼叫的唯一 ID。
型別	字串	必須是 `"web_search_call"`
狀態	字串	Web 搜尋工具呼叫的狀態。 `in_progress`、`searching`、`completed`、`failed`其中之一。

即時對話檔案搜尋呼叫項目

檔案搜尋呼叫回應項目。

Field	類型	Description
id	字串	檔案搜尋工具呼叫的唯一標識符。
型別	字串	必須是 `"file_search_call"`
查詢	string[]	Optional. 檔案搜尋所使用的查詢。
狀態	字串	檔案搜尋工具呼叫的狀態。其中之一`in_progress`為， `searching`， `completed`， `incompletefailed`，，。
results	FileSearchResult 的陣列	Optional. 檔案搜尋結果。

檔案搜尋結果

單一檔案搜尋結果條目。

Field	類型	Description
檔案識別碼 (file_id)	字串	Optional. 檔案的唯一 ID。
filename	字串	Optional. 檔案的檔名。
分數	編號	Optional. 檔案搜尋結果的相關性分數。
收發簡訊	字串	Optional. 檔案中與查詢相符的文字內容。
attributes	地圖	Optional. 用於篩選檔案搜尋結果的鍵值對。

行動搜尋

網路搜尋行動作為網路搜尋通話的一部分被記錄。

Field	類型	Description
型別	字串	必須是 `"search"`。
查詢	字串	Optional. 搜尋關鍵字。
來源	ActionSearchSource 陣列	Optional. 搜尋所用的資料來源。

行動搜尋源

一個由網頁搜尋動作所引用的來源網址。

Field	類型	Description
型別	字串	必須是 `"url"`。
url	字串	來源網址。

行動開放頁面

模型在網路搜尋過程中執行的開頁動作。

Field	類型	Description
型別	字串	必須是 `"open_page"`。
url	字串	模型所開啟的 URL。

動作尋找

模型在網頁搜尋過程中執行的頁面尋找動作。

Field	類型	Description
型別	字串	必須是 `"find"`。
模式	字串	在頁面內搜尋的模式或文字。
url	字串	搜尋該模式的頁面的 URL。

轉錄短語

一段帶有時間資訊的轉錄短語，回傳於 conversation.item.input_audio_transcription.completed。

Field	類型	Description
offset_milliseconds	整數	以毫秒為單位，從音訊開始的起點偏移。
duration_milliseconds	整數	片語的時值以毫秒計。
收發簡訊	字串	該短語的轉錄文本。
字句	轉錄字陣列	Optional. 片語中單字的時序資訊。
地區設定	字串	Optional. 轉錄的地點（例如， `en-US`）。
信賴度	編號	Optional. 轉錄的信心分數。

轉錄詞

一個帶有時間戳記的文字轉錄。

Field	類型	Description
收發簡訊	字串	文字轉錄。
offset_milliseconds	整數	以毫秒為單位，從音訊開始的起點偏移。
duration_milliseconds	整數	字長以毫秒計。

LogProbProperties

轉錄標記的對數機率資訊。

Field	類型	Description
Token	字串	那個標記文字。
logprob	編號	該標記的自然對數機率。
bytes	整數[]	Optional. 標記的 UTF-8 位元組表示。

即時項目狀態

談話項目的狀態。

允許的數值：

in_progress - 目前正在處理中
completed - 成功完成
incomplete - 不完整（中斷或失敗）

RealtimeContentPart

訊息中的內容部分。

RealtimeInputTextContentPart

文字內容部分。

Field	類型	Description
型別	字串	必須是 `"input_text"`
收發簡訊	字串	文本內容

RealtimeOutputTextContentPart

文字內容部分。

Field	類型	Description
型別	字串	必須是 `"text"`
收發簡訊	字串	文本內容

RealtimeInputAudioContentPart

音訊內容部分。

Field	類型	Description
型別	字串	必須是 `"input_audio"`
音效	字串	Optional. Base64 編碼的音訊資料
文字記錄	字串	Optional. 音訊文字記錄

RealtimeOutputAudioContentPart

音訊內容部分。

Field	類型	Description
型別	字串	必須是 `"audio"`
音效	字串	Base64 編碼的音訊資料
文字記錄	字串	Optional. 音訊文字記錄

回應物件

RealtimeResponse

回應物件代表模型推論回應。

Field	類型	Description
id	字串	Optional. 回應標識碼
物件	字串	Optional. 永遠 `"realtime.response"`
狀態	RealtimeResponseStatus	Optional. 回應狀態
狀態詳情	RealtimeResponseStatusDetails	Optional. 狀態詳細資料
輸出	RealtimeConversationResponse項目[]	Optional. 輸出項目
使用方式	Realtime使用情況	Optional. 代幣使用統計
conversation_id	字串	Optional. 相關對話識別碼
語音	RealtimeVoice	Optional. 聲音用於回應
模態	string[]	Optional. 使用的輸出模態
output_audio_format	RealtimeOutputAudioFormat	Optional. 所用音訊格式
溫度	編號	Optional. 使用溫度
max_response_output_tokens	整數或「inf」	Optional. 最大使用的代幣

即時回應狀態

回應狀態值。

允許的數值：

in_progress - 正在產生回應
completed - 回應成功完成
cancelled - 回應被取消
incomplete - 回應不完整（中斷）
failed - 回應失敗且錯誤

Realtime使用情況

代幣使用統計數據。

Field	類型	Description
total_tokens	整數	總使用代幣
input_tokens	整數	輸入標記
output_tokens	整數	產生的輸出代幣
輸入_代幣_詳細資訊	代幣詳細信息	輸入標記的分解
output_token_details	代幣詳細信息	輸出標記的分解

代幣詳細信息

詳細的代幣使用分析。

Field	類型	Description
cached_tokens	整數	Optional. 所使用的快取標記
text_tokens	整數	Optional. 使用的文字標記
audio_tokens	整數	Optional. 使用的音訊標記
reasoning_tokens	整數	Optional. 在輸出中產生的推理標記。僅適用於輸出代幣細節。

錯誤處理

RealtimeErrorDetails

錯誤資訊物件。

Field	類型	Description
型別	字串	錯誤類型（例如，`"invalid_request_error"`，） `"server_error"`
字碼	字串	Optional. 特定錯誤代碼
訊息	字串	人類可讀錯誤描述
param	字串	Optional. 與誤差相關的參數
event_id	字串	Optional. 導致錯誤的客戶端事件識別碼

即時對話請求項目

你可以用這個 RealtimeConversationRequestItem 物件透過 conversation.item.create 事件在對話中建立新項目。

這是一種聯合類型，可以是以下其中一種：

RealtimeSystemMessageItem

系統訊息項目。

Field	類型	Description
型別	字串	專案的型別。允許的值： `message`
角色	字串	訊息的角色。允許的值： `system`
內容	RealtimeInputTextContentPart 的陣列	訊息的內容。
id	字串	物品的唯一ID。用戶端可以指定 ID 來協助管理伺服器端的情境。如果客戶端沒有提供 ID，伺服器就會產生一個。

RealtimeUserMessageItem

一個使用者訊息項目。

Field	類型	Description
型別	字串	專案的型別。允許的值： `message`
角色	字串	訊息的角色。允許的值： `user`
內容	RealtimeInputTextContentPart 或 RealtimeInputAudioContentPart 陣列	訊息的內容。
id	字串	物品的唯一ID。用戶端可以指定 ID 來協助管理伺服器端的情境。如果客戶端沒有提供 ID，伺服器就會產生一個。

RealtimeAssistantMessageItem

一個助理訊息項目。

Field	類型	Description
型別	字串	專案的型別。允許的值： `message`
角色	字串	訊息的角色。允許的值： `assistant`
內容	RealtimeOutputTextContentPart 的陣列	訊息的內容。

RealtimeFunctionCallItem

一個函式呼叫項目。

Field	類型	Description
型別	字串	專案的型別。允許的值： `function_call`
名字	字串	要呼叫的函式名稱。
arguments	字串	函式的參數以 JSON 字串的形式呼叫。
call_id	字串	函式呼叫項目的 ID。
id	字串	物品的唯一ID。用戶端可以指定 ID 來協助管理伺服器端的情境。如果客戶端沒有提供 ID，伺服器就會產生一個。

RealtimeFunctionCallOutputItem

一個函式呼叫輸出項目。

Field	類型	Description
型別	字串	專案的型別。允許的值： `function_call_output`
call_id	字串	函式呼叫項目的 ID。
輸出	字串	函式呼叫的輸出，即帶有函式結果的自由形式字串，也可以是空的。
id	字串	物品的唯一ID。如果客戶端沒有提供 ID，伺服器就會產生一個。

即時MCPApproval回應項目

MCP 核准回應項目。

Field	類型	Description
型別	字串	專案的型別。允許的值： `mcp_approval_response`
approve	布林值	MCP申請是否獲得批准。
approval_request_id	字串	MCP 核准申請的 ID。
id	字串	物品的唯一ID。用戶端可以指定 ID 來協助管理伺服器端的情境。如果客戶端沒有提供 ID，伺服器就會產生一個。

RealtimeFunctionTool

即時端點所使用的函數工具定義。

Field	類型	Description
型別	字串	工具的類型。允許的值： `function`
名字	字串	函數的名稱。
描述	字串	功能說明，包括使用指引。例如，「使用此函式取得目前時間。」
parameters	物件	函式的參數以 JSON 物件的形式呈現。

即時項目狀態

允許的數值：

in_progress
completed
incomplete

RealtimeResponseAudioContentPart

Field	類型	Description
型別	字串	內容的類型。允許的值： `audio`
文字記錄	字串	音頻逐字稿。此性質是可作廢的。

RealtimeResponseFunctionCallItem

Field	類型	Description
型別	字串	專案的型別。允許的值： `function_call`
名字	字串	函式呼叫項目的名稱。
call_id	字串	函式呼叫項目的 ID。
arguments	字串	函式的參數呼叫 item。
狀態	RealtimeItemStatus	項目的狀態。

RealtimeResponseFunctionCallOutputItem

Field	類型	Description
型別	字串	專案的型別。允許的值： `function_call_output`
call_id	字串	函式呼叫項目的 ID。
輸出	字串	函式的輸出呼叫 item。

即時回應選項

Field	類型	Description
模態	陣列	回應的輸出模態。允許值︰`text` 和 `audio` 例如， `"modalities": ["text", "audio"]` 是啟用文字與音訊輸出模式的預設設定。若要啟用僅輸出文字，請設定 `"modalities": ["text"]`。你不能只啟用音訊。
instructions	字串	指令（系統訊息）用來引導模型的回應。
語音	RealtimeVoice	該會話所用的聲音作為模型回應。一旦聲音在模型的音訊回應中被使用，就無法更改。
工具	RealtimeTool 陣列	模型在該場次可用的工具。
tool_choice	RealtimeToolChoice	本次會話的工具選擇。
溫度	編號	模型的取樣溫度。允許的溫度值限制在 [0.6， 1.2]。預設為 0.8。
max_response_output_tokens	整數或「inf」	每個助理回應的最大輸出標記數，包含工具呼叫次數。指定一個介於 1 到 4096 之間的整數以限制輸出代幣。否則，將值設為「inf」以允許最大數量的標記。例如，若要限制輸出標記數為 1000，則設 `"max_response_output_tokens": 1000`。為了允許最大數量的標記，請設定 `"max_response_output_tokens": "inf"`。預設為 `"inf"`。
臨時應對	InterimResponseConfig	Optional. 在延遲或工具呼叫期間產生臨時回應的配置。
推理努力	ReasoningEffort	Optional. 限制推理模型的推理工作。請查閱模型文件中每個模型的支援數值。減少推理工作可能會導致回應更快，以及回應中用於推理的權杖較少。
交談	字串	控制回應會加入哪個對話。支援的值為 `auto` 與 `none`。這個 `auto` 值（或未設定此屬性）確保回應的內容會被加入該會話的預設對話中。將此屬性設為建立 `none` 一個帶外回應，且不會將項目加入預設對話中。預設 `"auto"`
中繼資料	地圖	最多可附加 16 對鍵值對，並可附加於物件上。這對於以結構化格式儲存物件的額外資訊非常有用。鍵長最多可為 64 個字元，數值最多可達 512 個字元。例如： `metadata: { topic: "classification" }`
interim_response	InterimResponseConfig	Optional. 在延遲或工具呼叫期間產生臨時回應的配置。會覆寫此回應的會話層級設定。
pre_generated_assistant_message	即時助理訊息項目	Optional. 一個預先產生的助理訊息，用來產生音訊回應，而不是讓模型自動生成文字。當提供時，伺服器會為預設文字產生音訊回應，繞過模型推論以產生文字。該訊息會被加入對話的上下文歷史紀錄中。訊息必須包含 `role` 和 `"assistant"content` 的單一文字內容部分。

即時回應會話

該 RealtimeResponseSession 物件代表 Realtime API 中的一個會話。它被用於部分伺服器活動，例如：

session.created
session.updated

Field	類型	Description
物件	字串	會話物件。允許的值： `realtime.session`
id	字串	會話的唯一ID。
型號	字串	本次會談所使用的模型。
模態	陣列	會話的輸出模態。允許值︰`text` 和 `audio` 例如， `"modalities": ["text", "audio"]` 是啟用文字與音訊輸出模式的預設設定。若要啟用僅輸出文字，請設定 `"modalities": ["text"]`。你不能只啟用音訊。
instructions	字串	指令（系統訊息）用來引導模型的文字與音訊回應。以下是一些範例說明，幫助引導文字與音訊回應的內容與格式： `"instructions": "be succinct"` `"instructions": "act friendly"` `"instructions": "here are examples of good responses"` 以下是一些範例指示，幫助引導音訊行為： `"instructions": "talk quickly"` `"instructions": "inject emotion into your voice"` `"instructions": "laugh frequently"` 雖然模型不一定總是遵循這些指示，但它們會提供所需的行為指引。
語音	RealtimeVoice	該會話所用的聲音作為模型回應。一旦聲音在模型的音訊回應中被使用，就無法更改。
input_audio_sampling_rate	整數	輸入音訊的取樣率。
input_audio_format	RealtimeAudioFormat	輸入音訊的格式。
output_audio_format	RealtimeAudioFormat	輸出音訊的格式。
input_audio_transcription	即時音頻輸入轉錄設置	音訊輸入轉錄的設定。此性質是可作廢的。
turn_detection	RealtimeTurnDetection	是該場次的轉彎偵測設定。此性質是可作廢的。
工具	RealtimeTool 陣列	模型在該場次可用的工具。
tool_choice	RealtimeToolChoice	本次會話的工具選擇。
溫度	編號	模型的取樣溫度。允許的溫度值限制在 [0.6， 1.2]。預設為 0.8。
max_response_output_tokens	整數或「inf」	每個助理回應的最大輸出標記數，包含工具呼叫次數。指定一個介於 1 到 4096 之間的整數以限制輸出代幣。否則，將值設為「inf」以允許最大數量的標記。例如，若要限制輸出標記數為 1000，則設 `"max_response_output_tokens": 1000`。為了允許最大數量的標記，請設定 `"max_response_output_tokens": "inf"`。
臨時應對	InterimResponseConfig	在延遲或工具呼叫期間產生臨時回應的配置。

實時回應狀態詳情

Field	類型	Description
型別	RealtimeResponseStatus	回應狀態。

RealtimeRateLimits項目

Field	類型	Description
名字	字串	本項目包含的費率限額物業名稱資訊。
limit	整數	此物業的最高設定限額。
剩餘	整數	剩餘配額會根據該費率限制物業的設定上限。
reset_seconds	編號	剩餘時間（以秒計）直到這個速率限制性質被重置。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-06-03

語音即時 2026-04-10 API 參考

端點與認證

WebSocket 端點

Authentication

客戶活動

session.update

活動結構

屬性

以 Azure 自訂語音為例

session.avatar.connect

活動結構

屬性

input_audio_buffer.附加

活動結構

屬性

input_audio_buffer.提交

活動結構

屬性

input_audio_buffer.清除

活動結構

屬性

conversation.item.create

活動結構

屬性

音訊內容範例

函式呼叫輸出的範例

MCP 核准回應範例

conversation.item.檢索

活動結構

屬性

對話.item.截斷

活動結構

屬性

刪除会话项

活動結構

屬性

回應.建立

活動結構

屬性

工具選擇的範例

動畫範例

預先產生的助理訊息範例

回應.取消

活動結構

屬性

output_audio_buffer.清除

活動結構

屬性

input_audio_buffer.附加

事件結構

屬性

input_audio_buffer.清除

事件結構

屬性

input_audio_buffer.提交

事件結構

屬性

伺服器事件

session.created

活動結構

屬性

session.updated

活動結構

屬性

session.avatar.connecting

活動結構

屬性

對話項目已創建

活動結構

屬性

音訊項目範例

conversation.item.檢索

活動結構

屬性

conversation.item.已截斷

事件結構

屬性

conversation.item.已刪除

活動結構

屬性

語音即時 `2026-04-10` API 參考