实时转录 | AGTCloud API Docs

通过 Realtime WebSocket 持续发送音频并接收增量及最终转录文本。

实时转录通过持久 WebSocket 连接接收连续音频，并按音频项返回增量文本和最终转录结果。它适合实时字幕、会议速记、通话转写和语音输入；如需一次上传完整录音文件，请使用音频转写接口。

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 应作为当前音频项的最终文本。