控制台

实时音视频对话

MOSS-Live 1.0 是面向自然、富有表现力的实时对话的全双工语音模型。它能够边听边说,支持自然打断,并将复杂推理和长程任务委派至客户自己的后台执行,在任务执行期间持续与用户交流。模型同时支持实时视频流输入,结合声音与画面理解对话场景,流式输出语音与文本。

Endpoint
WSS/v1/realtime
模型名称
moss-live-1.0
  1. 创建 API Key

    进入 API Key 管理平台创建密钥,并配置到服务端环境变量。

    环境变量
    MOSS_API_KEY=<your_api_key_here>
  2. 连接与鉴权

    使用服务端 WebSocket 客户端连接接口;在查询参数中指定模型,通过握手请求头传入 API Key。

    字段类型要求说明
    model: query string必填

    模型 ID:推荐稳定 ID,也支持快照 ID。通过 WebSocket 连接地址的 model 查询参数传入。

    Authorization: HTTP header必填

    Bearer <API Key>;只能放在 WebSocket 握手请求头中。

    连接地址
    wss://api.mosi.cn/v1/realtime?model=moss-live-1.0
    Authorization: Bearer $MOSS_API_KEY
  3. 创建会话

    连接成功后,先发送以下 JSON 文本帧:

    创建会话
    {
      "action": "attach_session",
      "session_id": null
    }

    收到 session_attached 后保存 data.session_id,再开始发送音频。基础对话可使用默认配置;需要人设、更换音色、工具或客户端委派时,按接口参考说明配置。

    如发送了 session.update,需等待 session.updated,确认 data.error 为空后再启用输入。连接或配置失败时先处理错误,不继续发送媒体。

  4. 发送实时语音

    先启用麦克风:

    启用麦克风
    {"action":"mic_state","enabled":true}

    采集音频并转换为 16 kHz、单声道、无文件头的 PCM S16LE,按实时速度以 WebSocket 二进制帧持续发送。说话结束后继续发送静音帧,使模型能够判断停顿。

    纯语音接入使用二进制帧直接发送 PCM。浏览器应用由服务端转发音频与事件,API Key 保存在服务端。播放期间继续采集和发送麦克风音频。

  5. 接收与展示回答

    会话持续返回模型语音,并提供用户语音文本和模型语音文本(transcript),可用于展示字幕或对话记录。按顺序播放返回的语音,并按需展示双方的语音文本。文本事件使用 {"action":"事件名","data":{…}},音频使用独立的 WebSocket 二进制帧。

    展示字幕与对话记录

    收到的事件应用处理
    input.transcript.updated / input.transcript.done用 data.text 更新或确认用户语音文本。
    output.transcript.updated / output.transcript.done用 data.text 更新或确认模型语音文本。

    data.text 是当前完整文本,更新时覆盖对应文本,不逐次拼接。已确认用户语音文本的修订及回复关联字段见接口参考。

    播放模型语音

    1. 收到 response.audio.started 时准备接收对应回复的音频。
    2. 每个 response.audio.context 携带下一条二进制音频的 run_id、turn_id、chunk_id。保存关联信息,按收到的顺序播放 48 kHz、单声道、PCM S16LE 音频。
    3. 片段实际播完时发送 playback.chunk.completed,原样携带 run_id、turn_id 和 chunk_id。
    4. 收到 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>"
    }

    播放回执由播放器的实际播放进度触发;字幕按文本事件独立更新。

  6. 处理打断并继续对话

    用户在模型说话时继续讲话,应用保持发送音频。收到 response.audio.stop 后,立即停止对应 run_id、turn_id 的播放并清空其待播音频,随后发送 playback.stopped。保持连接,继续接收下一次回复。

    先确认已完整播完的片段,再回传当前未完成片段已播放的部分时长 played_audio_ms;尚未开始播放时为 0。具体字段和计算规则见接口参考。

    收到 response.interrupted 后,根据 run_id、turn_id 将对应回复标记为已打断并结束,清除“进行中”状态。该事件作为此次回复的终态。保持连接并继续发送麦克风音频,接收下一次回复;按上述流程停止播放并发送 playback.stopped。

  7. 结束对话

    关闭 WebSocket,停止麦克风采集,清空待播放音频并释放播放器资源。启用视频时,同时停止摄像头或屏幕采集。

    结束会话
    ws.close();
    stream?.getTracks().forEach(track => track.stop());
    // 同时停止播放器并清空待播放音频。

    关闭连接后结束本次会话。计费信息请参阅计费说明。

  8. 验证接入

    • 说一句话,能看到用户语音文本并听到模型回答。
    • 模型回答时插话,旧回复停止播放,模型随后回应新的输入。
    • 正常播完一轮后,已发送播放确认,并收到 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 与执行器。

后台服务配置为可选项;实时对话和自定义工具可独立使用。

下一步