JoyInside 接入手册

主题

6.4 视觉对话接入 ​

视觉对话是 JoyInside 的"语音 + 图像理解"场景:设备持续采集视频帧图像上传云端,智能体将图像写入会话上下文缓冲区,作为视觉感知数据参与对话。

适用于带视觉识别功能的玩具、机器人(狗)等具身场景。

6.4.1 整体链路 ​

视觉数据通过 HTTP API 上报(不走 WebSocket 音频通道),但必须与 WS 对话的 sessionId 关联,云端才能把图像匹配到当前对话。

⚠ 视觉识别场景需先联系 JoyInside 运营人员协助申请开通权限,完成视觉识别智能体的接入。 视觉游戏技能

6.4.2 WebSocket 建连参数 ​

视觉对话的 WS 建联需额外带1个参数:needAsrPartial(开启ASR事件监听):

wss://ws.joyinside.com/soulmate/voiceChat/v1
  ?botId={botId}
  &sessionId={sessionId}
  &requestId={requestId}
  &needAsrPartial=true
参数说明
needAsrPartial触发图片上传时机。传 true 时服务端下发语音识别 IS_START 事件,客户端监听此事件作为触发图片上传的时机。

6.4.3 图像上传时机 ​

本地持续采集视频帧图像并缓存至本地,两种上传时机:

时机方式适用场景
定时上传按每秒 1 帧方式,读取本地缓存视频帧图像上传视觉实时感知的场景
事件触发上传收到 JoyInside 下行 IS_START 事件后上传减少链路开销,对视觉实时感知要求较低的场景

6.4.4 系统交互图 ​

视觉对话类场景

6.4.5 视觉图片上传 API ​

通过 API 方式上报客户端视觉采集图像,智能体将图像写入会话上下文缓冲区,作为视觉感知数据参与对话。

项目说明
URLhttps://api.joyinside.com/vision/client/image/report
请求方式POST
HeaderAuthorization: Bearer ${accessToken}
权限说明图像事件上报

⚠ 接口参数中 sessionId 必须是 WebSocket 建连时的 {sessionId},这样才能匹配到当前对话。sessionId 不一致会导致图像无法关联到对话上下文。

请求 Body ​

字段类型必选说明
requestIdString是每次请求唯一标识,建议使用 UUID
botIdString是终端设备唯一标识,每个终端用户必须用不同的 botId
sessionIdString是当前会话唯一标识。相同 sessionId 智能体可自动加载会话上下文
imgBase64String是图像 Base64 字符串,JPEG 格式
frameTimestampLong是图像采集时间戳(单位:毫秒)

响应 ​

字段类型必选说明
stateString是SUCCESS 成功 / FAILURE 失败
codeString是0000 成功,其他错误码
请求/响应示例(点击展开)

请求示例:

json
{
  "requestId": "1",
  "botId": "1",
  "sessionId": "12345678",
  "imgBase64": "imgBase64==",
  "frameTimestamp": 1761899917136
}

响应示例:

json
{
  "state": "SUCCESS",
  "code": "0000"
}

6.4.6 接入步骤 ​

  1. 平台注册:在 JoyInside 平台 完成注册,审核通过后完成基础配置
  2. 智能体接入:
    • 定制特殊智能体（技能）：视觉识别场景 需先联系 JoyInside 运营人员协助申请开通权限，然后完成选择视觉游戏智能体技能接入。
  3. WebSocket 语音链路接入:完成基础链路对接(带needAsrPartial=true,见 §6.4.2)
  4. 视觉图像上传:按 §6.4.3 时机上传,调用 §6.4.4 的 image/report API
  5. 配网功能:非 JoyInside 标准盒子需自行配网;标准盒子可用 JoyAI 小程序配网

下一步 ​