实时视频理解

使用 MOSS-VL-Realtime 通过一条 WebSocket 连接持续发送 JPEG、PNG 或 WebP 图像帧，在同一会话中提问并接收增量文本回答，适用于摄像头、屏幕等实时画面理解场景。

1. 创建 API Key

   进入 API Key 管理平台 创建密钥，并仅在服务端环境变量中使用。

   MOSS_API_KEY=<your_api_key_here>

2. 连接与鉴权

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

   字段类型要求说明

   model: query string必填

   模型 ID。使用 moss-vl-realtime-1.0；如需锁定快照，可使用 moss-vl-realtime-1.0-2026-09-09。放在 WebSocket 连接地址的查询参数中。

   Authorization: HTTP header必填

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

   wss://api.mosi.cn/v1/realtime?model=moss-vl-realtime-1.0
   Authorization: Bearer $MOSS_API_KEY

3. 配置会话

   连接成功后先接收 session.created，再发送一次 session.configure。等待服务端返回 session.configured 和 session.ready，之后才能发送画面或问题。

   字段类型要求说明

   type: string必填

   固定为 session.configure。

   prompt: string可选

   初始用户提示词，默认空字符串。

   max_new_tokens: integer可选

   每次新输入后重置的生成额度，默认 4096，不是整场会话的输出上限。

   include_usage: boolean可选

   是否推送 session.usage 观测事件，默认 false；不影响最终用量返回。

   {
     "type": "session.configure",
     "prompt": "请持续观察画面，回答我的问题。",
     "max_new_tokens": 128,
     "include_usage": false
   }

4. 发送实时画面

   将摄像头或屏幕画面转为图片帧。先发送一帧完成快速接通；需要持续观察时，按照相同流程继续发送后续帧。每帧先发送 input.frame 元数据，收到 input.frame.ready 后发送图片二进制，收到 input.frame.accepted 后再发送下一帧。发送画面本身不会自动生成回答，问题在下一步单独发送。

   字段类型要求说明

   type: string必填

   固定为 input.frame。

   seq_no: integer必填

   图像帧和提问共用从 0 开始的连续序列号。

   timestamp: number必填

   画面采集时间，单位秒；不得早于此前已接纳帧的时间戳。

   mime_type: string必填

   填写 image/jpeg、image/png 或 image/webp，且须与实际编码一致。

   {
     "type": "input.frame",
     "seq_no": 0,
     "timestamp": 0.0,
     "mime_type": "image/jpeg"
   }

   收到该帧的 input.frame.ready 后，发送 JPEG 文件的完整二进制字节；不能将图片放进 JSON、Base64 或 multipart。图片接纳后，可以继续发送下一帧，也可以进入下一步提问。

5. 发送问题

   画面帧发送完成后，单独发送 input.prompt 提问。问题不需要重复附带图片，服务端会根据已经接收的实时画面生成回答。final=false 的问题本身不会触发回答：提问后要继续按上一步的流程推送画面帧，回答在后续帧到达后才会出现。

   字段类型要求说明

   type: string必填

   固定为 input.prompt。

   seq_no: integer必填

   使用与画面帧连续的下一个序列号。

   prompt: string必填

   不能为空的问题文本。

   final: boolean可选

   默认 false；最后一次提问时可设为 true 结束会话。

   {
     "type": "input.prompt",
     "seq_no": 1,
     "prompt": "请描述画面中的细节。",
     "final": false
   }

   提问后继续发送下一帧，序号沿用连续的 seq_no，流程与上一步相同。本例在提问后再发送一帧，模型通常会在这一帧处理后开始输出回答；若仍静默，继续推帧即可。

   {
     "type": "input.frame",
     "seq_no": 2,
     "timestamp": 1.0,
     "mime_type": "image/jpeg"
   }

6. 接收与展示回答

   持续接收服务端事件，按顺序拼接 response.text.delta 的 delta。使用 response_id 区分回答段；即使正在等待输入确认，也要处理文本、错误和关闭事件。

   {"type":"response.text.delta","delta":"画面中有一辆车。","response_id":"resp_xxx","response_seq":0}
   {"type":"response.done","response_id":"resp_xxx","response_seq":0,"finish_reason":"stop"}

7. 结束会话

   如果还要继续提问，可以继续使用下一个序号；准备结束时，再将最后一次 input.prompt 设置为 final=true，并继续接收事件直至 session.done。如需提前停止，可发送 session.abort。这两种结束方式择一使用。

   {
     "type": "input.prompt",
     "seq_no": 3,
     "prompt": "请总结刚才看到的内容。",
     "final": true
   }

   {
     "type": "session.abort"
   }

8. 验证成功

   对本例的提问，确认在补发画面帧后收到并拼接了非空文本，最后收到 session.done 且 reason=completed。模型对部分画面或问题可能正常静默，不能把每次没有文本都判为调用失败；如果全程没有文本，先确认提问后是否继续推送了画面帧。

下一步