联犀开发者文档

人与AI视频

约 4104 字大约 14 分钟

2026-10-16

本页包含扩展设计，不能作为当前整场景已实现的承诺。参见支持范围、场景索引和命令手册。图中S编号只用于本文定位，不放入实际JSON。

前置条件

用户创建 aiVision 会话，模型必须声明视觉能力；摄像头初始 paused，语音与视频授权分开。这里只设计 WebRTC 音视频，不把 UDP 音频扩大为视频承载。

已实现独立本人视觉同意域、SQL仓储、专用创建校验、严格本人HTTP处理器及真实视频接收／有界采样解码基础；统一能力入口可保存显式aiVision声明，同时校验格式、AEC及共存用途，不签发取帧许可。HTTP签发必须经正式Runtime活Owner核验，未装配则拒绝；processorControl接入与摄像头→真实模型端云尚待完整验收。查询、撤销只依赖本人原账本，Owner失联或功能关闭也可撤销，不授予后继读帧许可。默认音频创建仍拒绝视觉请求；纯视觉声明也不能隐含开启未声明的AI语音用途。能力上报、真实视频解码或普通图片附件均不能代替本人摄像头同意及正式模型接通。本人同意签发/撤销的接口及嵌入式边界见命令05。

图中P代表经鉴权的平台业务控制器和媒体节点，不要求同一进程；A是用户应用，D是设备。控制图描述一种合法顺序，跨通道不承诺严格同序。

完整时序

报文索引

编号按图阅读；编号保留历史引用，不要求数值连续。字段定义以命令链接为准。

编号发送→接收Topic/接口方法及契约应答/等待状态或作用
S09-M01D→PSIG↑sessionCreatesessionCreated；10秒设备发起会话；平台验证设备能力、业务配置、资源与授权交集，不指定供应商。
S09-M02P→DSIG↓sessionCreated—；不等待仅代表创建并分配媒体资源成功，不代表媒体连通；成功必须带顶层 sessionId。
S09-M03D→PSIG↑mediaOffermediaAnswer；15秒设备为自身 Peer 的 offerer；初始与重协商同一方法，只允许一个在途 offer。
S09-M04P→DSIG↓mediaAnswer—；不等待完成 SDP 交换，仍需 ICE/DTLS 连通与 mediaState，不直接 established。
S09-M05D→PSIG↑mediaStaterequestAck；10秒报告设备实际传输状态。WebRTC 需 ICE/DTLS 成功；UDP 需有效会话媒体探测且平台也收到有效包。
S09-M06P→DSIG↓requestAck—；不等待仅确认状态上报；平台须独立验证自身连通状态。
S09-M07P→DSIG↓sessionEstablished—；不等待平台确认所需参与端媒体已连通后通知；不等于已收到首包或扬声器起播。
S09-M26A→PHTTP↑vision-consents/create原HTTP结果；2秒核权预算本人明确同意原摄像头/轨；活Owner核权与SQL原选择锁分开，不由管理员代签。未装配Authority拒绝，不从旧SQL重建在线证明。
S09-M27P→AHTTP↓视觉同意元数据—；不等待首次consentId/revision/本人明确expiresAt，不返回Owner/连接栅栏或画面；签发不是发布摄像头。
S09-M08A→PAPP↑interaction.processorControlHTTP受理；随后 interaction.result；10秒detach 先撤权再释放处理器；旁路失败只回本次操作错误，主通话继续。
S09-M09P→DSIG↓trackControl反方向 trackState；10秒publish/stop 控制源轨；subscribe/unsubscribe 仅本参与端订阅；pause/resume 只作用本端发布或订阅，不关闭其他观看者。请求不等于实际生效。
S09-M10D→PSIG↑trackState—；不等待双向实际状态；应答同 token 和 code，主动报告独立 token。设备失联只能标 unknown，不能假报 stopped。
S09-M11P→AAPP↓interaction.result—；不等待经 WS interaction.event 发给原操作者，原 token；设备通知不能充当应用请求应答。
S09-M12P→DSIG↓processorState—；不等待仅应用鉴权接口可附加；设备不能用事件授予自己或 AI 读流权限；旁路失败不挂主通话。
S09-M24D→PMSG↑inputSend按契约等待10秒核对补齐，不以受理替代完成
S09-M25P→DMSG↓requestAck应答或事件，无ACK核对补齐，不以受理替代完成
S09-M22P→DMSG↓respCreated应答或事件，无ACK核对补齐，不以受理替代完成
S09-M13P→DMSG↓respTextDone—；不等待最终完整文本取代增量；不是播放完成。
S09-M23P→DMSG↓respDone应答或事件，无ACK核对补齐，不以受理替代完成
S09-M28A→PHTTP↑vision-consents/revoke原HTTP结果；2秒本次预算本人按独立Consent修订撤权；到期/Owner失联仍可撤销，不授予旧排队帧继续消费。
S09-M29P→AHTTP↓原撤销结果—；不等待原expectedRevision重复返回首次撤销；不是设备已停止采集的实际回执。
S09-M14A→PAPP↑interaction.processorControlHTTP受理；随后 interaction.result；10秒detach 先撤权再释放处理器；旁路失败只回本次操作错误，主通话继续。
S09-M15P→DSIG↓trackControl反方向 trackState；10秒publish/stop 控制源轨；subscribe/unsubscribe 仅本参与端订阅；pause/resume 只作用本端发布或订阅，不关闭其他观看者。请求不等于实际生效。
S09-M16D→PSIG↑trackState—；不等待双向实际状态；应答同 token 和 code，主动报告独立 token。设备失联只能标 unknown，不能假报 stopped。
S09-M17P→AAPP↓interaction.result—；不等待经 WS interaction.event 发给原操作者，原 token；设备通知不能充当应用请求应答。
S09-M18P→DSIG↓processorState—；不等待仅应用鉴权接口可附加；设备不能用事件授予自己或 AI 读流权限；旁路失败不挂主通话。
S09-M19P→AAPP↓interaction.result—；不等待经 WS interaction.event 发给原操作者，原 token；设备通知不能充当应用请求应答。
S09-M20D→PSIG↑sessionEndsessionEnded；10秒设备主动结束整个会话，立即本地停采集/播放；平台撤销轨、处理器、密钥/令牌及资源占用。
S09-M21P→DSIG↓sessionEnded—；不等待主动结束用原 token 和 code；其他结束用独立事件 token 与 eventSeq。ended 是唯一会话终态。

逐条JSON

S09-M01 · sessionCreate

{
  "msgToken": "s09-127",
  "method": "sessionCreate",
  "params": {
    "purpose": "aiVision",
    "transport": "webrtc",
    "tracks": [
      {
        "trackId": "mic-1",
        "kind": "audio",
        "sourceId": "mic",
        "direction": "sendonly",
        "codec": "opus",
        "state": "requested"
      },
      {
        "trackId": "speaker-1",
        "kind": "audio",
        "sourceId": "speaker",
        "direction": "recvonly",
        "codec": "opus",
        "state": "requested"
      },
      {
        "trackId": "video-1",
        "kind": "video",
        "sourceId": "front",
        "direction": "sendonly",
        "codec": "H264",
        "state": "paused"
      }
    ],
    "cameraId": "front",
    "supportedInteractionModes": [
      "halfDuplex"
    ],
    "audioParams": {"format":"opus","sampleRate":48000,"channels":1,"frameDuration":20}
  }
}

S09-M02 · sessionCreated

{
  "msgToken": "s09-127",
  "method": "sessionCreated",
  "sessionId": "s09-session",
  "code": 200,
  "data": {
    "state": "negotiating",
    "selected": {
      "transport": "webrtc",
      "interactionMode": "halfDuplex",
      "audioParams": {
        "format": "opus",
        "sampleRate": 48000,
        "channels": 1,
        "frameDuration": 20
      }
    },
    "tracks": [
      {
        "trackId": "mic-1",
        "kind": "audio",
        "sourceId": "mic",
        "direction": "sendonly",
        "codec": "opus",
        "state": "requested"
      },
      {
        "trackId": "speaker-1",
        "kind": "audio",
        "sourceId": "speaker",
        "direction": "recvonly",
        "codec": "opus",
        "state": "requested"
      },
      {
        "trackId": "video-1",
        "kind": "video",
        "sourceId": "front",
        "direction": "sendonly",
        "codec": "H264",
        "state": "paused"
      }
    ]
  }
}

S09-M03 · mediaOffer

{
  "msgToken": "s09-128",
  "method": "mediaOffer",
  "sessionId": "s09-session",
  "params": {
    "mediaRevision": 1,
    "webrtc": {
      "iceMode": "complete",
      "sdp": "<SDP offer>"
    }
  }
}

S09-M04 · mediaAnswer

{
  "msgToken": "s09-128",
  "method": "mediaAnswer",
  "sessionId": "s09-session",
  "code": 200,
  "data": {
    "mediaRevision": 1,
    "webrtc": {
      "iceMode": "complete",
      "sdp": "<SDP answer>"
    }
  }
}

S09-M05 · mediaState

{
  "msgToken": "s09-129",
  "method": "mediaState",
  "sessionId": "s09-session",
  "params": {
    "mediaRevision": 1,
    "state": "connected"
  }
}

S09-M06 · requestAck

{
  "msgToken": "s09-129",
  "method": "requestAck",
  "sessionId": "s09-session",
  "code": 200,
  "data": {
    "requestMethod": "mediaState",
    "result": {
      "mediaRevision": 1,
      "state": "connected"
    }
  }
}

S09-M07 · sessionEstablished

{
  "msgToken": "s09-130",
  "method": "sessionEstablished",
  "sessionId": "s09-session",
  "eventSeq": 1,
  "data": {
    "state": "established",
    "mediaRevision": 1
  }
}

S09-M26 · vision-consents/create

{"msgToken":"s09-grant","sourceSessionId":"s09-session","cameraId":"front","trackId":"video-1","expectedMediaRevision":1,"expiresAt":1900000000000}

S09-M27 · 视觉同意元数据

{"code":200,"data":{"consent":{"consentId":"consent-vision","scope":"cameraAI","sourceSessionId":"s09-session","cameraId":"front","trackId":"video-1","mediaRevision":1,"revision":1,"grantedAt":1899999990000,"expiresAt":1900000000000,"revokedAt":0},"replay":false}}

上述HTTP字段已由独立严格处理器实现，不新增MQTT method；签发的正式活Authority及视觉端云仍需完整装配验证，受控Authority/SQL回归不替代实测。持久同意截止取本人明确值且不超过原会话deadline；两秒短核权只约束每次签发/取帧/模型提交。原token重放不刷新截止。取消分享先撤销独立同意，再按原M14–18请求停轨/释放处理器；实际停止仍取原trackState，失联不能补造stopped。排队帧在解码前及提交模型前分别核原同意修订与当前活来源，撤权/到期/连接或媒体换代后旧票据不得复用。SQL源行和旧快照不能重建活Owner；未知时不读帧、不调用模型，不挂断原主语音。

S09-M08 · interaction.processorControl

{
  "msgToken": "s09-131",
  "method": "interaction.processorControl",
  "sessionId": "s09-session",
  "params": {
    "processorId": "vision-1",
    "processor": "aiAssist",
    "operation": "attach",
    "sourceTrackIds": [
      "video-1"
    ],
    "consentIds": [
      "consent-vision"
    ]
  }
}

S09-M09 · trackControl

{
  "msgToken": "s09-132",
  "method": "trackControl",
  "sessionId": "s09-session",
  "eventSeq": 2,
  "params": {
    "trackId": "video-1",
    "operation": "publish",
    "mediaRevision": 1
  }
}

S09-M10 · trackState

{
  "msgToken": "s09-132",
  "method": "trackState",
  "sessionId": "s09-session",
  "code": 200,
  "data": {
    "trackId": "video-1",
    "state": "active",
    "mediaRevision": 1
  }
}

S09-M11 · interaction.result

{
  "msgToken": "s09-131",
  "method": "interaction.result",
  "sessionId": "s09-session",
  "code": 200,
  "data": {
    "operation": "interaction.processorControl",
    "state": "active",
    "processorId": "vision-1"
  }
}

S09-M12 · processorState

{
  "msgToken": "s09-133",
  "method": "processorState",
  "sessionId": "s09-session",
  "eventSeq": 3,
  "data": {
    "processorId": "vision-1",
    "processor": "aiAssist",
    "state": "active",
    "sourceTrackIds": [
      "video-1"
    ]
  }
}

S09-M24 · inputSend

{
  "msgToken": "s09-vision-query",
  "method": "inputSend",
  "sessionId": "s09-session",
  "params": {
    "inputId": "vision-input",
    "contents": [
      {
        "type": "text",
        "text": "请描述我正在分享的画面"
      }
    ],
    "outputModalities": [
      "text",
      "audio"
    ]
  }
}

S09-M25 · requestAck

{
  "msgToken": "s09-vision-query",
  "method": "requestAck",
  "sessionId": "s09-session",
  "code": 200,
  "data": {
    "requestMethod": "inputSend",
    "result": {
      "inputId": "vision-input",
      "state": "accepted"
    }
  }
}

S09-M22 · respCreated

{
  "method": "respCreated",
  "msgToken": "s09-audit-7",
  "sessionId": "s09-session",
  "messageSeq": 1,
  "data": {
    "respId": "vision-reply",
    "inputId": "vision-input"
  }
}

S09-M13 · respTextDone

{
  "msgToken": "s09-134",
  "method": "respTextDone",
  "sessionId": "s09-session",
  "messageSeq": 2,
  "data": {
    "respId": "vision-reply",
    "contentIndex": 0,
    "text": "画面里有一把椅子。"
  }
}

S09-M23 · respDone

{
  "method": "respDone",
  "msgToken": "s09-audit-8",
  "sessionId": "s09-session",
  "messageSeq": 3,
  "data": {
    "respId": "vision-reply",
    "inputId": "vision-input",
    "status": "completed",
    "contentCount": 1,
    "audioState": "sent"
  }
}

S09-M28 · vision-consents/revoke

{"consentId":"consent-vision","expectedRevision":1}

S09-M29 · 原撤销结果

{"code":200,"data":{"consent":{"consentId":"consent-vision","scope":"cameraAI","sourceSessionId":"s09-session","cameraId":"front","trackId":"video-1","mediaRevision":1,"revision":2,"grantedAt":1899999990000,"expiresAt":1900000000000,"revokedAt":1899999995000}}}

S09-M14 · interaction.processorControl

{
  "msgToken": "s09-135",
  "method": "interaction.processorControl",
  "sessionId": "s09-session",
  "params": {
    "processorId": "vision-1",
    "processor": "aiAssist",
    "operation": "detach",
    "sourceTrackIds": [
      "video-1"
    ]
  }
}

S09-M15 · trackControl

{
  "msgToken": "s09-136",
  "method": "trackControl",
  "sessionId": "s09-session",
  "eventSeq": 4,
  "params": {
    "trackId": "video-1",
    "operation": "stop",
    "mediaRevision": 1
  }
}

S09-M16 · trackState

{
  "msgToken": "s09-136",
  "method": "trackState",
  "sessionId": "s09-session",
  "code": 200,
  "data": {
    "trackId": "video-1",
    "state": "stopped",
    "mediaRevision": 1
  }
}

S09-M17 · interaction.result

{
  "msgToken": "s09-135",
  "method": "interaction.result",
  "sessionId": "s09-session",
  "code": 200,
  "data": {
    "operation": "interaction.processorControl",
    "state": "detached",
    "processorId": "vision-1"
  }
}

S09-M18 · processorState

{
  "msgToken": "s09-137",
  "method": "processorState",
  "sessionId": "s09-session",
  "eventSeq": 5,
  "data": {
    "processorId": "vision-1",
    "processor": "aiAssist",
    "state": "detached",
    "sourceTrackIds": [
      "video-1"
    ],
    "reason": "userStoppedSharing"
  }
}

S09-M19 · interaction.result

{
  "msgToken": "s09-131",
  "method": "interaction.result",
  "sessionId": "s09-session",
  "code": 422,
  "data": {
    "operation": "interaction.processorControl",
    "state": "failed",
    "reason": "visionModelUnavailable",
    "processorId": "vision-1"
  }
}

S09-M20 · sessionEnd

{
  "msgToken": "s09-138",
  "method": "sessionEnd",
  "sessionId": "s09-session",
  "params": {
    "reason": "userHangup"
  }
}

S09-M21 · sessionEnded

{
  "msgToken": "s09-138",
  "method": "sessionEnded",
  "sessionId": "s09-session",
  "code": 200,
  "data": {
    "state": "ended",
    "reason": "userHangup"
  }
}

媒体与本地动作

编号路径格式与约束
S09-R01D→PWebRTC ICE + DTLS 握手；完整 SDP 不代表握手成功；只有网络连通后才报告 connected。
S09-R02D→PWebRTC H264 轨；媒体节点按授权抽帧；平台记录采集时间、采样上限和上下文时窗，不把旧截图称为实时画面。
S09-R03P→DWebRTC Opus 回复音频轨；模型回复仍按respId关联控制与内容。

异常、状态与资源释放

以下JSON仅为报文正文；编号、方向、说明不发送。loop下一轮需分配新token/inputId；同一次请求重试必须沿用原token。字段以命令手册为准。

路由缩写均展开于公共约定。ACT/PROP超时以产品配置为准；内部工具以工具超时为准，不套用10秒设备统一信令超时。

停止分享先撤销模型取帧权限并丢弃在途帧，再等待设备停视频轨，语音可继续。再次分享已停止的轨需新 trackId 和必要的媒体重协商；不能 resume 已终结轨。已有预览不授予 AI 读取权。

能力不支持、无权限、设备拒绝、协商失败、断网、重复请求、过期会话及迟到媒体按S11共通失败流程和公共错误表处理。业务专属分支以本页为准，不因错误静默打开额外能力。

本例用文字问题触发一轮视觉回复；只有active的视觉处理器可把本次授权时窗内帧绑定vision-input，输入文本本身不授予取帧权限。语音提问另组合S02逐轮audioStart/Stop，或S20持续输入，不把建会话等同于已经说了一句话。

验证入口

检查本场景对应的支持范围，以及公共流程。示例可解析不等于网络、权限或硬件运行已验证。

更新日志

2026/10/16 16:04
查看所有更新日志
  • fe3a7-docs(AI与音视频): 按场景整理完整接入流程与命令契约于