OCTOS AUDIO API RTC v1.0
ENTERPRISE STREAMING AUDIO INFRASTRUCTURE

低延迟实时语音转写与合成 API

结合 LiveKit 自托管实时传输网络与 OminiX (Qwen3-ASR / Qwen3-TTS) 私有算力。 专为实时人机语音对话、长语音流式听写与即时播报打造，具备全双工低延迟、零入站公网暴露与完备的可观测性。

< 200 ms
P50 端到端转写延时
VAD 精准切句，分段即时送入模型推理
16k / 48k
广播级全双工音频
16kHz 进站识别，48kHz 升采样高清语音出站
Zero Inbound
内网安全架构
内网 Bridge 仅发起出站连接，模型资产不暴露公网
Qwen3 模型
100% 私有化算力
Qwen3-ASR + Qwen3-TTS 预设音色与语气控制

全链路系统架构

音频流经自托管 LiveKit SFU 传输保证抗丢包与低延时，信令与转写文本经 VPS 轻量控制面毫秒级转发。

客户端 / 业务前端
LiveKit Web/Mobile SDK 推流
WebSocket 订阅文本
RTC 音频 (Opus)
WebSocket (JSON)
LiveKit SFU & VPS 控制面
自托管 SFU 媒体转发
Rust Salvo 鉴权与会话分发
16kHz PCM
出站 WSS 文本
内网 Bridge & OminiX
LiveKit Python SDK 接收
Qwen3-ASR & TTS 本地推理

核心 API 端点速览

所有受保护接口通过标准 HTTP Bearer Token 鉴权。

方法 端点路径 功能说明 鉴权方式
POST /api/v1/sessions 创建实时语音会话，签发 LiveKit 房间临时凭证与专属 WebSocket 路由 Bearer Token
WS /ws/client/{sessionId} 订阅实时转写事件流（asr.partial 打字机片段、asr.final 最终断句） Session Cookie
POST /api/v1/sessions/{id}/speak 在频道内实时朗读文字（TTS），支持选择预设音色、语速与情感 Prompt Bearer / Cookie
POST /api/v1/sessions/{id}/commit 强制立即截断并提交当前正在识别的话语（跳过静音检测） Bearer / Cookie
DELETE /api/v1/sessions/{id} 正常结束会话，释放 LiveKit 房间与 Bridge 资源 Bearer / Cookie
GET /api/v1/status 获取服务运行状态、Bridge 连通性与当前并发会话容量 Public
GUIDE · OVERVIEW

系统设计与调用机制

Octos Audio API 是一套面向企业团队的全双工低延迟实时语音服务。服务由运行于云端的控制面 (Control Plane) 和部署在本地私有算力环境的桥接器 (Bridge) 协同提供。

为什么不是传统的文件上传接口？ 传统 ASR/TTS 接口要求客户端等待录音结束并将整个 WAV/MP3 文件 POST 上传，端到端延迟通常在 2~6 秒以上。 本项目采用「RTC 专网推流 + WebSocket 文本流」架构，说话过程实时切片并发推理，在用户停顿后 200ms 内即可完成最终断句。
GUIDE · AUTHENTICATION

鉴权认证规范

系统采用半公开服务机制（团队共用主凭证）。所有写入与会话级请求均需在 HTTP Header 中携带 Bearer Token：

HTTP Header 
Authorization: Bearer <CLIENT_ACCESS_TOKEN>

当浏览器创建会话成功后，控制面会自动签发限定路径的 HttpOnly Session Cookie，使后续的 WebSocket 连接无需在 URL 参数中暴露 Token。

GUIDE · QUICKSTART

快速开始示例

只需发起一个 POST 请求创建会话，即可获得 LiveKit 房间凭证及 WebSocket 订阅地址：

Terminal / Bash 
curl -X POST https://asr.example.com/api/v1/sessions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
Python 3 (httpx / requests) 
import httpx

BASE_URL = "https://asr.example.com"
TOKEN = "YOUR_ACCESS_TOKEN"

headers = {"Authorization": f"Bearer {TOKEN}"}
response = httpx.post(f"{BASE_URL}/api/v1/sessions", headers=headers, json={})
session = response.json()

print(f"Session ID: {session['sessionId']}")
print(f"LiveKit Room: {session['livekit']['room']}")
print(f"WS Path: {session['eventsWsPath']}")
Node.js / Browser (Fetch) 
const res = await fetch("https://asr.example.com/api/v1/sessions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${YOUR_ACCESS_TOKEN}`,
    "Content-Type": "application/json"
  },
  body: "{}"
});
const session = await res.json();
console.log("Created session:", session.sessionId);
API REFERENCE

创建会话 · POST /api/v1/sessions

请求控制面初始化一个双向实时通信会话，动态签发 LiveKit 房间级短期凭据（JWT)。

响应结果 (201 Created)

Response JSON 
{
  "sessionId": "e7fa699f-3507-4e6a-a006-25f0e9b2512a",
  "state": "starting",
  "expiresAtMs": 1727025600000,
  "eventsWsPath": "/ws/client/e7fa699f-3507-4e6a-a006-25f0e9b2512a",
  "demoMode": false,
  "rtcProvider": "livekit",
  "livekit": {
    "url": "wss://rtc.example.com:9443",
    "room": "asr-8bf2a0...",
    "identity": "client-1001",
    "token": "eyJhbGciOi..."
  }
}
CLIENT INTEGRATION

LiveKit RTC 音频推流与订阅

客户端引入 LiveKit Web / Mobile SDK，加入 livekit.room 指定的房间并采集音频推流。Bridge 会作为远端受众接收 16kHz PCM 进行 VAD 和 ASR。

JavaScript (livekit-client SDK) 
const room = new LivekitClient.Room();

// 监听远端音频发布（用于实时收听 TTS 播报）
room.on(LivekitClient.RoomEvent.TrackSubscribed, (track) => {
  if (track.kind === 'audio') {
    const element = track.attach();
    element.play();
    document.body.appendChild(element);
  }
});

// 入会并发布麦克风（自动启用 AEC / NS / AGC）
await room.connect(livekit.url, livekit.token);
await room.localParticipant.setMicrophoneEnabled(true, {
  echoCancellation: true,
  noiseSuppression: true,
  autoGainControl: true
});
EVENT PROTOCOL

WebSocket 实时事件协议

连接 wss://asr.example.com/ws/client/{sessionId} 后，Bridge 将实时推送以下 JSON 事件：

asr.partial
流式中间打字机片段。在用户讲话未停顿时持续高频推送。
{ "type": "asr.partial", "sessionId": "...", "utteranceId": "...:1", "seq": 3, "text": "形式上说赛题应该" }
asr.final
最终断句结果。当 VAD 检测到静音或客户端主动 commit 时下发，附带各链路耗时 metrics。
{
  "type": "asr.final",
  "sessionId": "...",
  "utteranceId": "...:1",
  "seq": 4,
  "text": "形式上说，赛题应该不需要百分之百做正确。",
  "metrics": {
    "bridge": { "asrTotalMs": 286.4, "endpointMs": 420.0 }
  }
}
tts.started / tts.finished
TTS 朗读生命周期事件。tts.started 包含文字字符数，播放完后下发 tts.finished。
API REFERENCE

语音合成播报 · POST /api/v1/sessions/{id}/speak

在指定的活跃会话中触发 TTS 合成。音频直接推入 RTC 频道，用户无需轮询下载音频文件。

当前支持预设音色选择、语速调整和语气提示词，尚未接入音色创建、参考录音上传或声音克隆。

请求体字段规范 (JSON)

参数名 类型 必填 说明与限制
text string 是 待朗读文本，1~500 个字符。支持中文标点与英文。
voice string 否 预设音色标识。省略时使用 Bridge 配置的默认音色（默认 serena）。中文预设包括 serena, vivian, uncle_fu, dylan, eric；英文预设包括 ryan, aiden。可用音色取决于 Bridge 加载的 TTS 模型，填写新名字不会创建音色。
speed number 否 语速倍率。范围 0.2 ~ 3.0，默认 1.0。
instruct string 否 调整预设音色的语气或情感，最多 200 字。如 "温柔亲切地"、"非常严肃地"。此参数不会创建新音色。
cURL 示例 
curl -X POST https://asr.example.com/api/v1/sessions/YOUR_SESSION_ID/speak \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "你好，我是 Octos 实时语音助手。很高兴与你交流！",
    "voice": "serena",
    "speed": 1.0,
    "instruct": "温柔亲切地"
  }'
API REFERENCE

断句与会话释放

POST /api/v1/sessions/{id}/commit 立即截断并提交当前话语。适用于客户端用户点击“发送”或松开按键的手动打断场景。
DELETE /api/v1/sessions/{id} 释放会话。建议在页面卸载（pagehide/beforeunload）或通话挂断时调用。
REFERENCE

错误码字典

HTTP Error Code 含义与处置建议
401 unauthorized 缺少有效 Bearer Token 或 Token 错误。请确认已设置正确的团队访问密钥。
409 session_busy 服务已达到最大并发承载上限（SESSION_CAPACITY）。请稍后再试或释放闲置会话。
503 bridge_offline 内网 Bridge 处于离线状态。请联系管理员确保 Mac 上的 Bridge 与 OminiX 实例正常运行。
400 invalid_text / invalid_speed TTS 朗读文本超长（>500字）或语速参数不在允许区间（0.2 ~ 3.0）。
404 session_not_found 会话已超时注销或不存在。需重新调用 POST /api/v1/sessions。
会话状态 待机
会话 ID —
Bridge 算力 检测中
运行模式 RTC 真实推流
浏览器麦克风
LiveKit RTC 网络
内网 Bridge
OminiX Qwen3
LIVE ASR

实时语音转写

点击上方“开始识别”，允许麦克风权限后即可开始讲话...

TTS SPEAK

实时语音合成与频道播报

日常问答 技术报告 长句测试
1.0x
TTS 就绪
TRACE & METRICS

端到端延时追踪观测

最新一句延时估算
—
P50 延时
—
P95 延时
—
有效样本数
0
最新解析断句

尚未收到最终识别结果。

RTC 网络统计：等待数据

分段延时瀑布 (Waterfall)

开始识别并产生语音后，此处将呈现各链路阶段的耗时分解。

展开控制面运行日志