实时音视频对话
MOSS-Live 1.0 是面向自然、富有表现力的实时对话的全双工语音模型。它能够边听边说,支持自然打断,并将复杂推理和长程任务委派至客户自己的后台执行,在任务执行期间持续与用户交流。模型同时支持实时视频流输入,结合声音与画面理解对话场景,流式输出语音与文本。
/v1/realtimemoss-live-1.0创建 API Key
进入 API Key 管理平台创建密钥,并配置到服务端环境变量。
环境变量 MOSS_API_KEY=<your_api_key_here>连接与鉴权
使用服务端 WebSocket 客户端连接接口;在查询参数中指定模型,通过握手请求头传入 API Key。
字段类型要求说明模型 ID:推荐稳定 ID,也支持快照 ID。通过 WebSocket 连接地址的 model 查询参数传入。
Bearer
<API Key>;只能放在 WebSocket 握手请求头中。连接地址 wss://api.mosi.cn/v1/realtime?model=moss-live-1.0 Authorization: Bearer $MOSS_API_KEY创建会话
连接成功后,先发送以下 JSON 文本帧:
创建会话 { "action": "attach_session", "session_id": null }收到
session_attached后保存data.session_id,再开始发送音频。基础对话可使用默认配置;需要人设、更换音色、工具或客户端委派时,按接口参考说明配置。如发送了
session.update,需等待session.updated,确认data.error为空后再启用输入。连接或配置失败时先处理错误,不继续发送媒体。发送实时语音
先启用麦克风:
启用麦克风 {"action":"mic_state","enabled":true}采集音频并转换为 16 kHz、单声道、无文件头的 PCM S16LE,按实时速度以 WebSocket 二进制帧持续发送。说话结束后继续发送静音帧,使模型能够判断停顿。
纯语音接入使用二进制帧直接发送 PCM。浏览器应用由服务端转发音频与事件,API Key 保存在服务端。播放期间继续采集和发送麦克风音频。
接收与展示回答
会话持续返回模型语音,并提供用户语音文本和模型语音文本(transcript),可用于展示字幕或对话记录。按顺序播放返回的语音,并按需展示双方的语音文本。文本事件使用
{"action":"事件名","data":{…}},音频使用独立的 WebSocket 二进制帧。展示字幕与对话记录
收到的事件 应用处理 input.transcript.updated/input.transcript.done用 data.text更新或确认用户语音文本。output.transcript.updated/output.transcript.done用 data.text更新或确认模型语音文本。data.text是当前完整文本,更新时覆盖对应文本,不逐次拼接。已确认用户语音文本的修订及回复关联字段见接口参考。播放模型语音
- 收到
response.audio.started时准备接收对应回复的音频。 - 每个
response.audio.context携带下一条二进制音频的run_id、turn_id、chunk_id。保存关联信息,按收到的顺序播放 48 kHz、单声道、PCM S16LE 音频。 - 片段实际播完时发送
playback.chunk.completed,原样携带run_id、turn_id和chunk_id。 - 收到
response.audio.done且对应回复的音频已全部实际播完后,发送playback.completed。
例如,一个音频片段播完后发送:
音频片段播放完成 { "action": "playback.chunk.completed", "run_id": "<收到的 run_id>", "turn_id": "<收到的 turn_id>", "chunk_id": "<收到的 chunk_id>" }整段回复播完后发送:
整段回复播放完成 { "action": "playback.completed", "run_id": "<收到的 run_id>", "turn_id": "<收到的 turn_id>" }播放回执由播放器的实际播放进度触发;字幕按文本事件独立更新。
- 收到
处理打断并继续对话
用户在模型说话时继续讲话,应用保持发送音频。收到
response.audio.stop后,立即停止对应run_id、turn_id的播放并清空其待播音频,随后发送playback.stopped。保持连接,继续接收下一次回复。先确认已完整播完的片段,再回传当前未完成片段已播放的部分时长
played_audio_ms;尚未开始播放时为 0。具体字段和计算规则见接口参考。收到
response.interrupted后,根据run_id、turn_id将对应回复标记为已打断并结束,清除“进行中”状态。该事件作为此次回复的终态。保持连接并继续发送麦克风音频,接收下一次回复;按上述流程停止播放并发送playback.stopped。结束对话
关闭 WebSocket,停止麦克风采集,清空待播放音频并释放播放器资源。启用视频时,同时停止摄像头或屏幕采集。
结束会话 ws.close(); stream?.getTracks().forEach(track => track.stop()); // 同时停止播放器并清空待播放音频。关闭连接后结束本次会话。计费信息请参阅计费说明。
验证接入
- 说一句话,能看到用户语音文本并听到模型回答。
- 模型回答时插话,旧回复停止播放,模型随后回应新的输入。
- 正常播完一轮后,已发送播放确认,并收到
output.transcript.done和response.ended(data.status=completed)。 - 关闭对话后,麦克风、视频采集和播放器均已停止。
后台服务配置
后台服务负责接收 MOSS-Live 委派的复杂推理和长程任务,并异步回传进度与结果。你可以使用已适配好的 Pi,也可以接入自己的 Harness。
方式一:使用 Pi
Pi 已完成适配,配置后台模型的服务商、Base URL、模型 ID 和 API Key 即可使用。需要 Node.js 22.19.0 或以上,支持 macOS 和 Linux;Pi 随依赖安装。
使用配套示例启动 Pi 并验证对话:
npx @mossai/mosslive@0.1.0 demo按终端提示完成配置并输入 MOSS API Key 与后台模型 Key,打开终端给出的本地地址开始对话。配置保存在 moss-live.config.json;密钥在启动时输入,也可通过 MOSS_API_KEY 和 CUSTOMER_BACKEND_KEY 环境变量提供。
示例默认启用只读工具 read / grep / find / ls,可通过 pi.tools 调整权限。在已有应用中使用 Pi,见接口参考中的 Pi 接入示例。
方式二:接入自己的 Harness
通过同一套 JavaScript SDK 接入自己的 Harness,实现任务执行、进度回传、结果返回和取消处理。可先生成适配项目:
npx @mossai/mosslive@0.1.0 init-adapter --directory my-adapter项目包含执行器模板、AGENTS.md 和契约测试。按指南完成适配后,将执行器接入实时连接。具体接口见接口参考:JavaScript SDK 与执行器。
后台服务配置为可选项;实时对话和自定义工具可独立使用。