AGTCloud API Docs
文件指南API Reference整合與資源更新與幫助
即時互動

即時互動

透過 Realtime WebSocket 處理即時文字、音訊與函式呼叫。

OpenAI Realtime 使用持久連線和雙向事件處理即時文字、音訊與函式呼叫。用戶端傳送工作階段、音訊緩衝區、對話項和回應控制事件,伺服器端持續回傳工作階段狀態、轉錄、文字、音訊、函式參數和錯誤事件。

本頁以 WebSocket 作為主要連線方式。連線時請將 MODEL_ID 替換為目前帳戶可見且支援 Realtime 的模型 ID。

典型情境包括即時語音對話、會議即時轉錄與語音助理、即時翻譯、語音轉錄、即時程式碼互動以及伺服器端即時整合。連線可同時承載文字與音訊,並透過事件處理 VAD、函式呼叫和狀態更新。

WSS
wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID

認證與連線

WebSocket 認證

伺服器端應用透過 Bearer API Key 建立 WSS 連線,並在握手請求中帶上 Realtime Beta Header。

項目值
連線位址wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID
AuthorizationBearer your-api-key
OpenAI-Betarealtime=v1

長期 API Key 只應在可信伺服器端使用,不要將它寫入瀏覽器、行動應用程式套件或公開程式碼儲存庫。所有連線都應使用 HTTPS/WSS。

暫時權杖

用戶端連線時,可先由可信伺服器端建立有效期為一分鐘、僅用於單一連線的暫時權杖。

POST https://api.agtcloud.cn/v1/realtime/sessions
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "model": "MODEL_ID",
  "voice": "verse"
}

連線流程

WebSocket 主流程由伺服器端直接使用 API Key 建立連線,握手成功後在同一連線中傳送用戶端事件並接收伺服器端事件。

WebRTC 流程則由用戶端先向自己的應用程式伺服器請求暫時權杖,應用程式伺服器呼叫工作階段 API 建立權杖;用戶端隨後產生 SDP Offer、提交至 Realtime 端點並接收 SDP Answer,最後透過 oai-events 資料通道交換 JSON 事件。

WebSocket 連線範例

下列範例分別展示 Node.js、Python、事件傳送和事件接收。建立連線後,用戶端傳送 JSON 事件,伺服器端也會以 JSON 事件持續回傳結果。

WSSWebSocket 連線與事件收發
import WebSocket from 'ws';

const ws = new WebSocket('wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID', {
  headers: {
    Authorization: 'Bearer your-api-key',
    'OpenAI-Beta': 'realtime=v1',
  },
});

ws.on('open', () => {
  console.log('Connected to server.');
});

ws.on('message', (message) => {
  console.log(JSON.parse(message.toString()));
});

WebRTC 串接說明

目前建議使用 WebSocket。使用 WebRTC 前,請先確認目標模型是否支援;以下範例說明暫時權杖、SDP、音訊軌道和資料通道的基本連線架構。

工作階段、音訊與對話

Realtime 支援純文字、語音以及文字與音訊混合對話。工作階段設定可以包含輸入和輸出音訊格式、語音、溫度、最大輸出長度、工具以及 VAD 參數。

  • 輸入與輸出音訊格式:pcm16、g711_ulaw、g711_alaw。
  • 範例語音選項:alloy、echo、shimmer。
  • VAD 設定包括閾值、語音前綴填充和靜音持續時間。
  • 對話由工作階段、對話項、內容部分和回應事件共同推進。

具體事件欄位請在下方事件瀏覽器中檢視;共用參數和值域集中列在「共用類型」。

事件 Reference

選擇事件以檢視欄位定義和 JSON 範例。可以切換事件方向、依類別篩選或搜尋事件名稱。

用戶端事件 · Session

session.update

更新工作階段的預設設定。

欄位類型必填說明範例值
event_id字串否用戶端產生的事件識別碼event_123
type字串否事件類型session.update
modalities字串陣列否模型可回應的模態類型["text", "audio"]
instructions字串否預設到模型呼叫前的系統指令"請用簡潔、準確的語言回答。"
voice字串否模型使用的語音類型alloy、echo、shimmer
input_audio_format字串否輸入音訊格式pcm16、g711_ulaw、g711_alaw
output_audio_format字串否輸出音訊格式pcm16、g711_ulaw、g711_alaw
input_audio_transcription.model字串否用於轉錄的模型whisper-1
turn_detection.type字串否語音檢測類型server_vad
turn_detection.threshold數字否VAD 激活閾值(0.0-1.0)0.8
turn_detection.prefix_padding_ms整數否語音開始前包含的音訊長度500
turn_detection.silence_duration_ms整數否檢測語音停止的靜音持續時間1000
tools陣列否模型可用的工具清單[]
tool_choice字串否模型選擇工具的方式auto/none/required
temperature數字否模型取樣溫度0.8
max_output_tokens字串或整數否單次回應最大token數"inf"/4096
JSON 範例
{
  "event_id": "event_123",
  "type": "session.update",
  "modalities": [
    "text",
    "audio"
  ],
  "instructions": "請用簡潔、準確的語言回答。",
  "voice": "alloy",
  "input_audio_format": "pcm16",
  "output_audio_format": "pcm16",
  "input_audio_transcription": {
    "model": "whisper-1"
  },
  "turn_detection": {
    "type": "server_vad",
    "threshold": 0.8,
    "prefix_padding_ms": 500,
    "silence_duration_ms": 1000
  },
  "tools": [],
  "tool_choice": "auto",
  "temperature": 0.8,
  "max_output_tokens": "inf"
}

共用類型

以下折疊區匯總速率限制、函式呼叫、音訊、VAD、工具、模型、事件、工作階段、對話項、內容、回應、轉錄、音訊流和 WebRTC 參數表。

速率限制事件參數表4 個欄位
欄位類型必填說明選用值或範例
name字串是限制名稱範例值:requests_per_min
limit整數是限制值範例值:60
remaining整數是剩餘可用量範例值:45
reset_seconds整數是重置時間(秒)範例值:35
函式呼叫參數表4 個欄位
欄位類型必填說明選用值或範例
type字串是函數類型範例值:function
name字串是函數名稱範例值:get_weather
description字串否函數描述範例值:Get the current weather
parameters物件是函數參數定義範例值:{"type": "object", "properties": {...}}
音訊格式參數表4 個欄位
欄位類型必填說明選用值或範例
sample_rate整數—取樣率可選值:8000, 16000, 24000, 44100, 48000
channels整數—聲道數可選值:1 (單聲道), 2 (立體聲)
bits_per_sample整數—取樣位數可選值:16 (pcm16), 8 (g711)
encoding字串—編碼方式可選值:pcm16, g711_ulaw, g711_alaw
語音檢測參數表3 個欄位
欄位類型必填說明選用值或範例
threshold浮點數—VAD 激活閾值預設值:0.5;範圍:0.0-1.0
prefix_padding_ms整數—語音前綴填充(毫秒)預設值:500;範圍:0-5000
silence_duration_ms整數—靜音檢測長度(毫秒)預設值:1000;範圍:100-10000
工具選擇參數表2 個欄位
欄位類型必填說明選用值或範例
tool_choice字串—工具選擇方式可選值:auto, none, required
tools陣列—可用工具清單可選值:[{type, name, description, parameters}]
模型設定參數表4 個欄位
欄位類型必填說明選用值或範例
temperature浮點數—取樣溫度範圍/可選值:0.0-2.0;預設值:1.0
max_output_tokens整數或字串—最大輸出長度範圍/可選值:1-4096/"inf";預設值:"inf"
modalities字串陣列—回應模態範圍/可選值:["text", "audio"];預設值:["text"]
voice字串—語音類型範圍/可選值:alloy, echo, shimmer;預設值:alloy
事件通用參數表3 個欄位
欄位類型必填說明選用值或範例
event_id字串是事件的唯一識別碼範例值:event_123
type字串是事件類型範例值:session.update
timestamp整數否事件發生的時間戳(毫秒)範例值:1677649363000
工作階段狀態參數表3 個欄位
欄位類型必填說明選用值或範例
status字串—工作階段狀態可選值:active, ended, error
error物件—錯誤資訊可選值:{"type": "error_type", "message": "error message"}
metadata物件—工作階段中繼資料可選值:{"client_id": "web", "session_type": "chat"}
對話項目狀態參數表3 個欄位
欄位類型必填說明選用值或範例
status字串—對話項目狀態可選值:completed, in_progress, incomplete
role字串—傳送者角色可選值:user, assistant, system
type字串—對話項目類型可選值:message, function_call, function_call_output
內容類型參數表3 個欄位
欄位類型必填說明選用值或範例
type字串—內容類型可選值:text, audio, transcript
format字串—內容格式可選值:plain, markdown, html
encoding字串—編碼方式可選值:utf-8, base64
回應狀態參數表3 個欄位
欄位類型必填說明選用值或範例
status字串—回應狀態可選值:completed, cancelled, failed, incomplete
status_details物件—狀態詳情可選值:{"reason": "user_cancelled"}
usage物件—使用統計可選值:{"total_tokens": 50, "input_tokens": 20, "output_tokens": 30}
音訊轉錄參數表4 個欄位
欄位類型必填說明選用值或範例
enabled布林值—是否啟用轉錄範例值:true
model字串—轉錄模型範例值:whisper-1
language字串—轉錄語言範例值:en, zh, auto
prompt字串—轉錄提示詞範例值:"Transcript of a conversation"
音訊流參數表3 個欄位
欄位類型必填說明選用值或範例
chunk_size整數—音訊塊大小(位元組)可選值:1024, 2048, 4096
latency字串—延遲模式可選值:low, balanced, high
compression字串—壓縮方式可選值:none, opus, mp3
WebRTC 設定參數表3 個欄位
欄位類型必填說明選用值或範例
ice_servers陣列—ICE 伺服器清單預設值:[{"urls": "stun:stun.l.google.com:19302"}]
audio_constraints物件—音訊約束預設值:{"echoCancellation": true}
connection_timeout整數—連線逾時(毫秒)預設值:30000

錯誤處理與恢復

Realtime 錯誤通常來自連線、認證、音訊或工作階段四類問題:

類型常見原因處理方向
連線錯誤網路中斷、握手失敗或連線設定錯誤檢查 WSS 網址、網路和握手請求,依有限次數重新連線
認證錯誤API Key 無效、暫時權杖過期或與 API 網址不相符更新認證資訊,並確保 API Key 與請求使用的 API 網址相符
音訊錯誤裝置權限、格式不支援或編解碼不相符檢查裝置權限、取樣與編碼設定,再重新建立音訊鏈路
工作階段錯誤工作階段超時、併發限制或事件狀態不一致保存錯誤事件,重新建立工作階段,必要時降級到非即時API

恢復策略可以包括自動重連、工作階段恢復、有限重試和功能降級。發生錯誤時,應優先讀取 error 事件,保存其 event_id、error.type、error.code、error.message 和關聯事件資訊,再決定是否重發。