Realtime 接口

使用 OpenAI Realtime 兼容 WebSocket 路由进行实时交互。

GET /v1/realtime

Realtime 使用 WebSocket 连接，适合低延迟语音对话、实时事件流和双向交互。连接会经过鉴权、模型限流和渠道分发。

默认示例模型为 。

当前可用模型

模型	说明
	Realtime 实时语音 / 事件流
	Realtime 预览模型

调试台可编辑 session.update 的会话字段示意；实际联调请使用下方 WebSocket 连接示例（浏览器原生 WebSocket 通常无法自定义请求头，需网关注入或使用支持自定义头的客户端）。

连接地址

将 API Base URL 的 https 换成 wss（或 http 换成 ws），再拼接路径：

wss://<API_HOST>/v1/realtime

示例（占位符在构建时替换）：

https://octopusx.ai/v1/realtime

也可通过查询参数指定模型，例如：/v1/realtime?model=gpt-realtime。

请求头

名称	类型	必填	说明
	string	是	请求身份认证。使用 Bearer Token，示例：。若客户端不便设置 WebSocket 请求头，可按网关配置使用临时 token 或由代理层注入

连接示例

const base = "https://octopusx.ai".replace(/^http/, "ws")
const ws = new WebSocket(`${base}/v1/realtime`)

// 若运行环境支持自定义头，请带上 Authorization
// headers: { Authorization: "Bearer YOUR_API_KEY" }

ws.onopen = () => {
  ws.send(
    JSON.stringify({
      type: "session.update",
      session: {
        model: "gpt-realtime",
        modalities: ["text"],
        instructions: "你是一个实时语音助手。"
      }
    })
  )
}

ws.onmessage = (event) => {
  console.log(JSON.parse(event.data))
}

会话配置（session.update）

连接建立后，客户端可随时发送 更新会话；服务端以 返回生效后的完整配置。只更新消息中出现的字段；清空 传空字符串，清空 传空数组，关闭 传 。

名称	类型	必填	说明
	array	否	模型响应模态，默认 ；设为 可禁用音频输出
	string	否	Realtime 模型，可选值见上方「当前可用模型」；也可经 URL model 查询参数指定
	string	否	默认系统指令，引导回复内容、格式与音频行为
	string	否	回复声音，默认 。内置： / / / / / / / / / 。输出过音频后不可更换
	string	否	输入音频格式，默认 （24kHz PCM）；可选 、
	string	否	输出音频格式，默认 ；可选 、
	object	否	输入音频转写配置，默认关闭
	object	否	服务端轮流发言检测；传 关闭后需手动触发响应
	object	否	输入音频降噪；传 关闭
	number	否	采样温度，范围 –，默认
	integer | string	否	单次响应最大输出 token（含工具调用）；– 或 （默认）
	array	否	可调用工具列表，目前支持 function 工具
	string | object	否	工具选择：（默认）/ / ，或指定函数对象

input_audio_transcription

名称	类型	必填	说明
	string	否	转写模型，如 、、
	string	否	输入语言（ISO-639-1），如 、
	string	否	可选提示词，引导转写风格或补充专有名词

turn_detection

名称	类型	必填	说明
	string	否	检测类型，默认 ；可选
	number	否	仅 。VAD 激活阈值，默认 ，范围 –
	integer	否	仅 。语音起点前保留音频时长（毫秒），默认
	integer	否	仅 。判定说完所需静音（毫秒），默认
	string	否	仅 。抢答积极程度： / / / （默认，等价 ）
	boolean	否	发言结束时是否自动生成响应，默认
	boolean	否	新发言开始时是否打断进行中响应，默认

input_audio_noise_reduction

名称	类型	必填	说明
	string	否	降噪类型：（近讲）或 （远场）

常见事件

客户端事件

事件	说明
	更新会话配置
	追加 Base64 编码的输入音频
	提交输入音频缓冲（关闭 VAD 时手动提交）
	清空输入音频缓冲
	创建对话项
	删除对话项
	触发模型响应
	取消进行中的响应

服务端事件

事件	说明
/	会话创建 / 配置已更新
/	VAD 检测到发言开始 / 结束
	输入音频转写完成
/	响应开始 / 完成
	文本增量
/	音频增量 / 音频输出完成
/	输出音频转写增量 / 完成
	函数调用参数生成完成
	错误事件
	速率限制更新

响应示例（session.updated 示意）

{
  "type": "session.updated",
  "event_id": "event_abc123",
  "session": {
    "id": "sess_abc123",
    "object": "realtime.session",
    "model": "gpt-realtime",
    "modalities": ["text"],
    "instructions": "你是一个实时语音助手。",
    "voice": "alloy"
  }
}

相关接口

• 对话接口
• 多模态响应接口
• 文字系列概览