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 流程则由客户端先向自己的应用服务器请求临时令牌,应用服务器调用会话接口创建令牌;客户端随后生成 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 地址匹配
音频错误设备权限、格式不支持或编解码不匹配检查设备权限、采样与编码设置,再重新建立音频链路
会话错误会话超时、并发限制或事件状态不一致保存错误事件,重新建立会话,必要时降级到非实时接口

恢复策略可以包括自动重连、会话恢复、有限重试和功能降级。发生错误时,应优先读取 error 事件,保存其 event_id、error.type、error.code、error.message 和关联事件信息,再决定是否重发。