应用与内部接口命令

约 11643 字大约 39 分钟

2026-10-16

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

应用传输接口：已实现的基础与业务边界

本节四条REST接口已实现；commands接IPC预览及显式启用的独立对讲打开/SDP/连通报告/结束。interaction.trackControl当前只支持预览自身订阅，对讲不套用预览屏障；对讲额外成员应用入口仍待实现。打开预览可显式单向监听，对讲须callId及独立IM/设备准入和平台IPC.Talk配置。其余业务命令及WebSocket主动推送仍待实现。REST路径不是MQTT Topic，不计为新增设备method。纯视频/混合监听/源控制已有Linux C++解码验证；对讲Go Runtime双向实际Opus通过，正式C++对讲E2E仍未完成。

所有调用均须经过登录鉴权与企业上下文初始化，并启用Signaling。端点由平台随机分配并绑定当前用户／企业；客户端自报端点标签、已知其他用户端点或管理员身份不能替代该绑定。以下路径统一前缀为/api/v1/im/interaction。

POST路径	请求	成功data及含义
`/endpoints/register`	无请求正文	`endpointId:string`、`expiresAt:int64`；独立端点固定有效一小时，时间为Unix毫秒；它不替代登录Token
`/events`	`endpointId:string`、`limit:int`（1～32）	`list:[{deliveryId:string,event:object}]`；event为完整原interaction.result/state信封，不是JSON字符串；无消息返回空数组
`/events/ack`	`endpointId:string`、`deliveryIds:string[]`（1～32，不能重复）	`acknowledged:int`；本端点已经处理的通知数量；同ID再次确认幂等成功
`/commands`	`endpointId:string`、`command:object`（本章原应用命令信封）	`accepted:boolean`、`msgToken:string`、`replay:boolean`；原请求已持久受理，不表示设备接听或媒体连通

commands传输包装的唯一契约：只允许endpointId与command两个字段，总JSON不超过65536字节，command必须是对象而不是JSON字符串。HTTP handler严格检查重复键、深度、Unicode和安全整数，未知顶层字段及主体自报拒绝。命令章节及场景JSON展示的是command对象本身，HTTP发送时包装如下，不给设备信封添加endpointId：

{"endpointId":"<registered-endpoint>","command":{"msgToken":"open-view","method":"interaction.open","target":{"productID":"p-demo","deviceName":"device-demo"},"params":{"purpose":"ipcLiveView","cameraId":"front"}}}

项目实际REST使用HTTP200及统一结果封装，成功data为{"accepted":true,"msgToken":"open-view","replay":false}；HTTP受理不是接通。设备／应用原结果进入持久events，状态以真实协商、双方报告及服务器连通推进；应用受理不能冒充设备状态。端点先鉴权，再按原token持久幂等；错误或未实现方法不返回accepted。原请求重放不会重新创建观看或分配媒体。

门铃原interaction.control决策重试：在原端点、原邀请token、完整请求指纹及固定保留窗内返回原结果；未确认结果仍用原投递，已确认后重新投递相同结果但使用新的deliveryId。客户端须按原msgToken关联业务结果、按deliveryId确认本次传输；迟到旧ACK不能确认新投递。重试只推进投递水位，不推进业务eventSeq，不重新振铃、重新接听、延长授权或改变胜者。换命令／拒因的同token请求仍冲突，保留窗到期仍拒绝。该保证仅描述当前门铃决策，不推断所有旧业务已完成同样的ACK后重放接线。

APP endpointControl 的本人显式重放：原企业、用户、端点、会话、method、msgToken及完整请求指纹一致时，内部保留原已完成应答，HTTP仍只返回accepted／msgToken／replay元信息，完整结果经events消费；原结果尚待确认则复用同一deliveryId，已经确认则新建独立传输回执。新回执保持原完整正文、业务eventSeq、投递Sequence和原ExpiresAt，迟到旧ACK只能确认旧回执。它不再次提交接续、不改变父会话修订或目标媒体，不续期；原投递过期或已被清扫时不创建新投递，缺行也不能被当作重新受理或推算新TTL的理由。events请求只有endpointId和limit，没有名册afterSeq游标；会议名册水位不用于过滤此结果。该保证仅覆盖本章新APP接续接口，不改变旧IM、/ai或action协议。

事件正文的唯一字段契约仍是本章interaction.result/state，不再另造通知方法。拉取按sessionId、投递水位和deliveryId排序，仅返回本端点可读、未确认、未过期且已可投递的事件；重复拉取保留同deliveryId及正文。不同会话和APP／MQTT通道不承诺跨通道同序。

客户端流程：注册并保存本端点 → commands包装原业务命令并使用该端点 → 拉取并解析原信封 → 按deliveryId去重并应用状态 → 批量确认已处理ID。失败重试不得在处理前确认；HTTP确认仅是应用传输确认，不是设备Broker确认、动作完成或音视频已播放。任一ID跨用户／企业／端点、属于设备投递、未知或过期时，整批拒绝，不部分清除。

普通HTTP请求采用10秒客户端超时；注册失败重试会生成新端点，不能推断创建了业务会话。拉取失败允许原请求重试；确认失败原ID重试。绑定不会因拉取自动续期，客户端须在过期前结束相关会话；一小时后注册新端点不接管未声明对应能力的端点会话。长期会话续期／端点转移尚未实现，不隐式放行。服务端错误使用现有公共错误封装，参数／绑定错误明确拒绝，缓存或数据库异常不泄漏底层地址与凭据。

interaction.open · APP↑

项目	契约
Topic/接口	`POST /api/v1/im/interaction/commands`
发送→接收	已鉴权应用→平台
消息类型	请求
对应应答	HTTP受理；随后 interaction.result
触发与状态变化	平台验证目标、策略和能力后邀请设备；HTTP202的accepted不是接通。
前置条件	会话/参与端有效，满足方法语义；结束/失败事件允许清理非终态会话
超时与重试	10秒；最多原token重试2次；事件形式不等待ACK
幂等与迟到	遵循公共约定；终态不复活；旧sessionId/媒体代次拒绝或丢弃，不影响新资源
失败	请求按对应应答方法返回实际code和data.reason；异步失败单独事件，不以成功字段包装错误
适用场景	S01、S05、S06、S07、S08

字段	类型	必填条件	枚举／默认及含义
purpose	string	必填	业务目的
cameraId	string	相机场景必填	摄像头
callId	string	ipcTalk必填	已存在且当前用户已加入的IM群通话ID；平台另检成员和音频许可，不自动入会。预览不允许携带此字段
listenAudio	boolean	IPC预览可选	省略为false；true显式请求摄像头侧麦克风单向Opus发布。拒绝null、字符串、数字；不代表开启IM会议对讲、扬声器或AI取帧
callType	string	通话必填	voice/video
recordingId	string	回放必填	录像ID
clip	object	recordPlayback可选	精确startMs/endMs安全整数，相对录像半开区间；省略请求整份，平台邀请仍明确固化范围
sourceLanguage	string	翻译必填	源语言
targetLanguage	string	翻译必填	目标语言

字段	类型	必填条件	枚举／默认及含义
callId	string	必填	原IM群通话ID；必须等于 `sessionId` 原媒体腿持久绑定的会议。
participantId	string	必填	规范安全正整数字符串用户ID；本人表示自退，他人表示主持移出。不能使用 `user-b`、前导零、自报角色。
expectedMemberEpoch	integer	必填	1～9007199254740991；原IM音权读取的目标 `memberEpoch`。退出重入递增；不接受null、小数、指数或字符串。

字段	类型	必填条件	枚举／默认及含义
sourceLanguage	string	必填	BCP47
targetLanguage	string	必填	BCP47
speakerId	string	必填	指定说话人
configRevision	uint	必填	递增配置号

POST路径	严格请求字段	成功data与副作用
`/create`	msgToken、sourceSessionId、cameraId、trackId、expectedMediaRevision、expiresAt	`{consent,replay}`：consent只含下列10项公共元数据；仅签同意，不打开摄像头/处理器
`/get-one`	consentId	`{consent}`：本人原元数据，revokedAt=0仅表示未撤销；到期或会话结束可查询，不等于当前仍授权取帧
`/revoke`	consentId、expectedRevision	`{consent}`：新revision及首次revokedAt；相同原expectedRevision重复返回首次结果，不刷新任何租约

物模型

AI与音视频接入

协议参考

场景

应用与内部接口命令