即時轉錄 | AGTCloud API Docs

透過 Realtime WebSocket 持續傳送音訊並接收增量及最終轉錄文字。

即時轉錄透過持久 WebSocket 連線接收連續音訊，並按音訊項目回傳增量文字和最終轉錄結果。它適合即時字幕、會議速記、通話轉錄和語音輸入；如需一次上傳完整錄音檔案，請使用音訊轉錄 API。

gpt-live-transcribe 適合低延遲增量轉錄；gpt-transcribe 適合提交完整語音段後進行高準確度轉錄，並可在最終事件中回傳偵測到的語言。連線和工作階段中的模型應保持一致。

WSS

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

認證與連線

伺服器端應用應在 WebSocket 握手中使用 Bearer API Key：

項目	值
連線位址	`wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID`
Authorization	`Bearer your-api-key`
OpenAI-Safety-Identifier	可選的去識別化終端使用者識別碼

一般瀏覽器的 WebSocket API 無法自訂 Authorization Header，因此不要把長期 API Key 寫入前端 HTML、JavaScript 或用戶端套件。瀏覽器產品應由可信後端建立連線或提供受控的短期認證機制。

音訊輸入要求

本文件中的輸入音訊採用 PCM16 little-endian、24 kHz、單聲道，不包含 WAV 或其他容器檔頭。input_audio_buffer.append 中的 audio 是原始 PCM 位元組的 Base64 字串。

即時傳送時建議使用較小且穩定的音訊片段；單一事件不應超過 15 MiB。音訊格式、取樣率或容器處理錯誤會造成轉錄失敗。

工作階段設定

session.update 的 session.type 固定為 transcription。轉錄設定位於 session.audio.input.transcription：

欄位	說明
`model`	與連線 URL 一致的轉錄模型
`prompt`	業務場景、說話環境和上下文提示
`keywords`	專名、縮寫和產品名提示，不保證強制輸出
`languages`	預期語言清單，例如 `zh-cn`、`en`
`delay`	即時模型的延遲設定，例如 `low`

noise_reduction.type=near_field 適合耳麥，far_field 適合會議室或筆記型電腦麥克風；設為 null 可關閉降噪。

手動提交與伺服器端 VAD

turn_detection: null：用戶端傳送音訊後呼叫 input_audio_buffer.commit，適合由業務邏輯明確控制分段。
伺服器端 VAD：設定閾值、語音前綴和靜音時長，由伺服器端自動識別語音開始與結束。

手動模式下不要提交空緩衝區。啟用 VAD 時，可根據 speech_started 和 speech_stopped 更新錄音介面，但最終轉錄仍應以 completed 事件為準。

連線範例

下列範例假設 audio.pcm 已轉換為 PCM16、24 kHz、單聲道原始音訊。實際即時應用應持續傳送較小音訊區塊，而不是一次讀取完整錄音。

import fs from 'node:fs';
import WebSocket from 'ws';

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

ws.on('open', async () => {
  ws.send(JSON.stringify({
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": { "type": "audio/pcm", "rate": 24000 },
        "noise_reduction": { "type": "near_field" },
        "transcription": {
          "model": "MODEL_ID",
          "prompt": "繁體中文客服通話",
          "keywords": ["AGTCloud", "API 閘道"],
          "languages": ["zh-cn", "en"]
        },
        "turn_detection": null
      }
    }
  }
}));

  const audio = fs.createReadStream('audio.pcm', { highWaterMark: 4800 });
  for await (const chunk of audio) {
    ws.send(JSON.stringify({
      type: 'input_audio_buffer.append',
      audio: chunk.toString('base64'),
    }));
    await new Promise((resolve) => setTimeout(resolve, 100));
  }
  ws.send(JSON.stringify({ type: 'input_audio_buffer.commit' }));
});

ws.on('message', (message) => {
  const event = JSON.parse(message.toString());
  if (event.type.endsWith('.delta')) process.stdout.write(event.delta);
  if (event.type.endsWith('.completed')) console.log('\n', event.transcript);
});

事件 Reference

用戶端使用工作階段和音訊緩衝區事件控制輸入；伺服器端使用 Item ID 關聯增量文字、最終文字和錯誤。不同音訊項的完成順序可能不同，因此應按 item_id 聚合文字。

用戶端事件 · Session

session.update

設定即時轉錄工作階段、輸入音訊和分段方式。

欄位	類型	必填	說明	範例值
`event_id`	字串	否	用戶端產生的事件 ID。	`evt_session_001`
`type`	字串	是	固定為 session.update。	`session.update`
`session.type`	字串	是	固定為 transcription。	`transcription`
`session.audio.input.format.type`	字串	是	本文使用 PCM16 little-endian。	`audio/pcm`
`session.audio.input.format.rate`	整數	是	PCM 輸入取樣率。	`24000`
`session.audio.input.noise_reduction.type`	字串	否	近場或遠場降噪。	`near_field`
`session.audio.input.transcription.model`	字串	是	與連線 URL 一致的轉錄模型。	`MODEL_ID`
`session.audio.input.transcription.prompt`	字串	否	轉錄場景和上下文提示。	`中文客服通話`
`session.audio.input.transcription.keywords`	字串陣列	否	專名、縮寫或產品名提示。	`["AGTCloud", "API 網關"]`
`session.audio.input.transcription.languages`	字串陣列	否	預期語言清單。	`["zh-cn", "en"]`
`session.audio.input.transcription.delay`	字串	否	即時模型延遲設定。	`low`
`session.audio.input.turn_detection`	物件或 null	是	null 使用手動提交；物件啟用伺服器端 VAD。	`null`

JSON 範例

{
  "event_id": "evt_session_001",
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": {
          "type": "audio/pcm",
          "rate": 24000
        },
        "noise_reduction": {
          "type": "near_field"
        },
        "transcription": {
          "model": "MODEL_ID",
          "prompt": "中文客服通話",
          "keywords": [
            "AGTCloud",
            "API 網關"
          ],
          "languages": [
            "zh-cn",
            "en"
          ],
          "delay": "low"
        },
        "turn_detection": null
      }
    }
  }
}

錯誤處理與恢復

類型	常見原因	處理方式
握手失敗	WSS 網址、API Key 或請求 Header 錯誤	修正連線參數後重新建立連線
參數錯誤	工作階段層級、欄位值或模型不一致	讀取 `error.event_id` 並修正對應用戶端事件
音訊錯誤	格式、取樣率、Base64 或檔頭不符合要求	重新轉換音訊並清空緩衝區
轉錄失敗	音訊不可辨識或目前音訊項處理失敗	記錄失敗 Item ID，只重試對應語音段
連線中斷	網路中斷或工作階段失效	停止傳送音訊，依有限次數重新連線並重新建立工作階段

增量文字可能被後續結果修訂，不應在收到 delta 時寫入不可變記錄；只有 completed 中的 transcript 應作為目前音訊項的最終文字。