联犀开发者文档

通用请求应答

约 1542 字大约 5 分钟

2026-10-16

本页按 Topic、method 和方向定义完整契约。字段表与JSON中的可选扩展不等于当前全部启用，实际接入前请查支持范围；应用REST封装见应用接入。

关联和状态边界

requestAck只用于下表十类上行；请求与应答在同一路由族，msgToken原样回传，data.requestMethod明确原请求。成功code=200、data.result必填；失败用实际code、data.requestMethod和data.reason，不携带伪造成功结果。无eventSeq/messageSeq，不需要再次ACK；重复按认证主体＋路由族＋原method＋token重放缓存。

10秒未收到可按同token最多重试2次；先查去重记录再检查状态或revision。相同token不同正文409。邀请的30秒/工具执行的60秒期限不因重试延长。一个ACK只确认下表的受理结果，不能从“200”推断用户已接通、媒体已连通、回复已结束或硬件已停声。

sessionCreated、mediaAnswer、trackState等有独立资源/业务含义的应答仍保留。平台收到未知上行请求method时，以对应下行路由requestAck返回400 unsupportedMethod，data.requestMethod回显未知值，只作关联、不执行；不得将requestAck作为新请求而形成ACK循环。未知会话404，不隐式创建。

各请求成功result结构

字段定义只维护在此表；原请求params仍在各命令页。未列字段不自动增加语义。

respCancel 的 UDP／WebRTC 成功 ACK 可以只返回原 respId，表示请求已受理，仍须等待原回复的 respDone；不得补造 state=cancelled。None 文字会话必须返回实际的 cancelled/alreadyFinished 状态。两者都不能代替设备实际停声确认；尚未收到音频也可以取消已创建的内容回复。

requestMethod路由result字段及含义ACK之后还需等待什么
mediaStateSIGmediaRevision:uint（成功必填；已接受代次）；state:string（成功必填；connected/failed）平台校验所需端后sessionEstablished；不能仅信端自报
trackStateSIGtrackId:string（成功必填；原上报轨）；state:string（成功必填；原active/paused/stopped/failed）；mediaRevision:uint（成功必填；原媒体代次）仅无code的设备主动实态上报；确认已持久收录，不代替整组mediaUpdated或硬件验收
audioStartSIGinputId:string（成功必填；已启用输入段）后续识别/回复；不代表已有语音
audioStopSIGinputId:string（成功必填；停止段）只停止输入；待处理回复可能继续
respCancelSIGrespId:string（成功必填；取消目标）；state:string（None成功必填，UDP／WebRTC可选；存在时仅cancelled/alreadyFinished）respDone及必要的audioSpeechInterrupted；不是硬件停声
inputSendMSGinputId:string（成功必填；原输入ID）；state:string（成功必填；accepted）respCreated→内容→respDone
toolCallSubmitMSGtoolCallId:string（成功必填；原调用ID）；respId:string（可选；原回复ID）；state:string（成功必填；accepted）；continuation:string（可选；accepted/unknown，原AISVR是否明确接纳结果）模型续答→respDone；结果受理不保证续答成功
capabilityReportSIGacceptedRevision:uint（成功必填；已接受的能力快照）能力登记不授予权限；创建会话仍需求交集
sessionAcceptSIGstate:string（成功必填；negotiating）sessionEstablished：所需参与端媒体连通
sessionRejectSIGstate:string（成功必填；ended）；reason:string（必填；拒绝原因）sessionEnded：终态及资源释放

toolCallSubmit 的 state=accepted 只确认端结果已持久受理。continuation=accepted 仅表示原 AISVR 等待对象明确接纳，不表示回复或播放完成；unknown 表示未取得此确认。未声明对应能力的端忽略可选字段即可保持原行为；缺省或未知值均不能推断续答成功，仍只消费后续原 respId 的内容及 respDone。unknown 不自动重发工具、不新建模型轮次；同 msgToken 重试仅重放原 ACK。

trackState主动事实放在data而非params，平台仍核对原会话、轨和mediaRevision，以及质量计划的requestToken／revision。带code的trackState是对trackControl的终态回执，不再产生requestAck，避免回执循环。确认单轨事实不能冒充全部轨已生效，见S19-M11／M13。

requestAck · SIG↓

  • Topic：$thing/down/signaling/{productID}/{deviceName}；平台→原请求设备。
  • 用途：确认本路由请求，保留原token与已分配sessionId。capabilityReport应答不携带sessionId。
  • 触发、超时、幂等和失败：见本页公共规则；扩展契约，须确认支持。应用用interaction.result，不转发设备MQTT ACK给应用冒充其应答。
  • 适用场景：S01–S20；全部成功result以本页表格为准。
字段类型必填条件含义
requestMethodstring必填原请求method；与token和路由联合关联
resultobject成功必填对应请求的成功正文；字段见上表
reasonstring失败必填稳定原因，不含敏感详情
currentRevisionuintrevision冲突可选服务器当前修订号

报文实例

{
  "msgToken": "s02-22",
  "method": "requestAck",
  "sessionId": "s02-session",
  "code": 200,
  "data": {
    "requestMethod": "audioStart",
    "result": {
      "inputId": "input-1"
    }
  }
}

对应S02-M09。请求失败时不要求result，但requestMethod始终必填。

requestAck · MSG↓

  • Topic：$thing/down/message/{productID}/{deviceName}；平台→原请求设备。
  • 用途：确认本路由请求，保留原token与已分配sessionId。capabilityReport应答不携带sessionId。
  • 触发、超时、幂等和失败：见本页公共规则；扩展契约，须确认支持。应用用interaction.result，不转发设备MQTT ACK给应用冒充其应答。
  • 适用场景：S09/S21/S22；全部成功result以本页表格为准。
字段类型必填条件含义
requestMethodstring必填原请求method；与token和路由联合关联
resultobject成功必填对应请求的成功正文；字段见上表
reasonstring失败必填稳定原因，不含敏感详情
currentRevisionuintrevision冲突可选服务器当前修订号

报文实例

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

对应S09-M25。请求失败时不要求result，但requestMethod始终必填。

更新日志

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