创建实时对话

连接与鉴权

使用 HTTP GET 升级为 WebSocket。连接地址为 wss://api.mosi.cn/v1/realtime，必须通过 model 查询参数指定模型；API Key 只能放在 Authorization 请求头中。

字段类型要求说明

model: query string是

模型 ID，固定为 moss-live-1.0，通过 WebSocket 地址的 model 查询参数传入。

user: query string否

调用方自己的稳定终端用户 ID，需 URL 编码；使用 memory_scope=user 时必填，重连时使用相同 user。示例：wss://api.mosi.cn/v1/realtime?model=moss-live-1.0&user=customer_001。

Authorization: HTTP header是

Bearer <API Key>；放在 WebSocket 握手的 Authorization 请求头中。

会话流程

阶段	客户端	服务端与判断
建立连接	完成 WebSocket 握手	连接打开后加入会话
配置	发送 attach_session，再发送 session.update	依次等待 session_attached、session.updated，确认 data.error 为空字符串
发送音频及视频	启用麦克风；画面启用 media.mode 与 video.state	同一连接接收音频和 JPEG 画面
回答	展示文本、播放语音并发送播放回执	接收 input.transcript.done、output.transcript.done 和 response.ended
继续或结束	继续输入，或关闭 WebSocket	本轮完成可继续；关闭连接结束会话

客户端事件

字段类型说明

attach_session: event

加入会话；收到 session_attached 后开始按在线时长计费。

session.update: event

设置人设与业务规则；收到 session.updated 后检查 data.error，非空时配置不生效。

mic_state: event

开启或关闭麦克风输入。

media.mode: event

视频或屏幕共享前启用 tagged-v1。

媒体	上行二进制格式
未启用 tagged-v1 的音频	裸 PCM S16LE；20 ms 为 640 字节，无 WAV 头。
启用 tagged-v1 的音频	0x00 + PCM 原始字节；20 ms 为 641 字节。关闭画面后仍保留前缀。
摄像头	0x01 + JPEG 原始字节，一张图片为一条消息。
屏幕共享	0x02 + JPEG 原始字节，一张图片为一条消息。

video.state: event

控制摄像头或屏幕画面；关闭画面不结束会话。

playback.chunk.completed: event

每个音频块实际播放完成后发送；字段放在消息顶层，不套 data。只确认实际播放完成的音频，不要等待回答文本结束才确认。

playback.completed: event

收到 response.audio.done 且本轮音频全部播放完成后发送。

video.stream_focus: event

设置主要关注的画面来源。

playback.stopped: event

收到 response.audio.stop 后停止对应播放并回传。

服务端事件

字段类型说明

session_attached: event

会话已加入；收到后再配置人设与业务规则。

session.updated: event

配置结果；data.error 为空字符串时启用媒体和麦克风。

input.transcript.updated: event

用户识别文本更新；data.text 为当前完整文本，替换显示，不要逐条追加。

input.transcript.done: event

用户识别文本完成。

output.transcript.updated: event

模型回答文本更新；data.text 为当前完整文本，替换显示，不要逐条追加。

output.transcript.done: event

模型回答文本完成。

response.interrupted: event

回答被打断；按 run_id、turn_id 将对应回答标记为已打断。

response.audio.context: event

保存音频上下文，与后续二进制音频按顺序配对。

response.audio.done: event

本轮音频发送完毕；实际播放全部完成后发送 playback.completed。

response.ended: event

本轮状态通知；不等同于会话结束。

error: event

错误事件；记录原因并释放连接及媒体资源。

response.audio.stop: event

停止对应语音播放，并发送 playback.stopped。

协议限制

项目	当前协议值与说明
音频	上行 16 kHz、下行 48 kHz，单声道 PCM S16LE；不带 WAV 头。说话结束后继续传静音。
媒体封装	tagged-v1：音频 0x00，摄像头 JPEG 0x01，屏幕 JPEG 0x02；关闭画面后音频仍保留前缀。
画面	每张 JPEG 一条二进制消息，不使用 Base64，不接受整段 MP4 或 H.264 码流。
传输	音频与画面复用同一 WebSocket。
画面处理	过载时可能保留最新画面并丢弃待处理旧帧，不保证逐帧分析。1 FPS、JPEG quality 0.8、摄像头长边 640 px、屏幕 1024 px 是客户端默认值，不是硬上限。

错误码

建连阶段的认证、权限、限流和通用 HTTP 错误，请参见错误码。以下仅列出 MOSS-LIVE 接口专属的协议错误。

错误码	触发条件	处理建议
memory_scope_requires_user	user 记忆范围缺少终端用户身份	传入稳定 user，或使用 session 范围。
memory_scope_immutable	重连时修改创建选项	按创建时选项重连；改变选项需新建会话。
invalid_memory_scope	参数值不合法	检查枚举值。

下一步

模型

查看 MOSS-LIVE 模型详情

查看模型 ID、模态支持与实时交互能力。

模型概览

查看模型列表

对比模型能力，选择适合当前场景的模型。

请求示例

import asyncio, json, os
import websockets

URL = "wss://api.mosi.cn/v1/realtime?model=moss-live-1.0"
HEADERS = {
    "Authorization": "Bearer " + os.environ["MOSS_API_KEY"],
}

async def main():
    async with websockets.connect(URL, additional_headers=HEADERS) as ws:
        await ws.send(json.dumps({"action": "attach_session"}))
        async for packet in ws:
            if isinstance(packet, bytes):
                # 配对 response.audio.context，按 48 kHz PCM S16LE 播放并回执。
                continue
            msg = json.loads(packet)
            data = msg.get("data") or {}
            action = msg.get("action")
            if action == "session_attached":
                await ws.send(json.dumps({"action": "session.update", "session": {
                    "persona": {"name": "小安", "prompt": "你是友好的助手小安。"},
                    "instructions": "请用一句简短的中文回答。"}}))
            elif action == "session.updated":
                if data.get("error"):
                    raise RuntimeError(str(msg))
                await ws.send(json.dumps({"action": "media.mode",
                    "binary_protocol": "tagged-v1"}))
                await ws.send(json.dumps({"action": "video.state",
                    "source": "camera", "enabled": True}))
                await ws.send(json.dumps({"action": "mic_state", "enabled": True}))
                # 从实时采集任务上传：
                # await ws.send(b"\x00" + pcm_bytes)   # 16 kHz PCM
                # await ws.send(b"\x01" + jpeg_bytes)  # 摄像头
                # await ws.send(b"\x02" + jpeg_bytes)  # 屏幕
            elif action == "error":
                raise RuntimeError(str(msg))
            else:
                print(action, data)
# 连接与控制示例；需另接实时采集、播放队列和回执逻辑。
asyncio.run(main())

import WebSocket from 'ws';
const ws = new WebSocket('wss://api.mosi.cn/v1/realtime?model=moss-live-1.0', {
  headers: { Authorization: `Bearer ${process.env.MOSS_API_KEY}` }
});
const send = (value: object) => ws.send(JSON.stringify(value));
ws.on('open', () => send({ action: 'attach_session' }));
ws.on('message', (packet, isBinary) => {
  if (isBinary) {
    // 按 response.audio.context 配对，播放 48 kHz PCM 并发送回执。
    return;
  }
  const msg = JSON.parse(packet.toString());
  const data = msg.data || {};
  if (msg.action === 'session_attached') {
    send({ action: 'session.update', session: {
      persona: { name: '小安', prompt: '你是友好的助手小安。' },
      instructions: '请用一句简短的中文回答。' } });
  } else if (msg.action === 'session.updated') {
    if (data.error) { console.error(msg); ws.close(); return; }
    send({ action: 'media.mode', binary_protocol: 'tagged-v1' });
    send({ action: 'video.state', source: 'camera', enabled: true });
    send({ action: 'mic_state', enabled: true });
  } else if (msg.action === 'error') { console.error(msg); ws.close(); }
});
// 会话就绪后，从实时采集任务发送，pcmBytes / jpegBytes 为采集数据：
function sendAudio(pcmBytes: Buffer) {
  ws.send(Buffer.concat([Buffer.from([0x00]), pcmBytes]));
}
function sendCamera(jpegBytes: Buffer) {
  ws.send(Buffer.concat([Buffer.from([0x01]), jpegBytes]));
}
function sendScreen(jpegBytes: Buffer) {
  ws.send(Buffer.concat([Buffer.from([0x02]), jpegBytes]));
}
// 说话结束后继续发送全 0 PCM。画面可先按 1 FPS 联调。
// 另接采集、播放和回执；测试结束调用 ws.close()。

响应示例

// 以下为独立接收的 WebSocket 事件示例。
{"action":"session_attached","data":{"session_id":"<session_id>","memory_scope":"session","delegation":"none"}}
{"action":"session.updated","data":{"error":""}}
{"action":"input.transcript.done","data":{"text":"画面里有什么？"}}
{"action":"output.transcript.done","data":{"text":"画面中有一张桌子。","run_id":"<run_id>","turn_id":"<turn_id>"}}
{"action":"response.audio.context","data":{"chunk_id":"<chunk_id>","run_id":"<run_id>","turn_id":"<turn_id>"}}
// <48 kHz 单声道 PCM S16LE 二进制；与上下文配对播放并回执>
{"action":"response.audio.done","data":{"run_id":"<run_id>","turn_id":"<turn_id>"}}
{"action":"response.ended","data":{"status":"completed","run_id":"<run_id>","turn_id":"<turn_id>"}}