协议模型

端点与 TLS

通道	对外 SDK 默认地址	明文兼容地址
Asset	`https://sdk-runtime.localhost:18082`	`http://127.0.0.1:17082`
Command WS	`wss://sdk-runtime.localhost:18090`	`ws://127.0.0.1:17090`
Video WS	`wss://sdk-runtime.localhost:18091`	`ws://127.0.0.1:17091`

对外 SDK 默认启用 SDK_TLS_ENABLED=1，并将 sdk-runtime.localhost 映射到 127.0.0.1。TLS 默认端口分别为 18082、18090、18091。客户端必须信任服务端证书或签发 CA；明文端点仅用于兼容场景。TLS 配置项、证书链和私钥要求请参考连接建立。

Command WS

对外 SDK 默认地址：

text

wss://sdk-runtime.localhost:18090

Command WS 承载 JSON 请求和响应。握手 URL 不携带 API Key、session token 或业务参数。

自定义 TLS 部署使用 wss://<tls-host>:18090，其中 <tls-host> 必须与服务端证书匹配。无论使用 ws 还是 wss，客户端均通过 auth.create_session 在连接建立后提交 API Key。

Request

json

{
  "request_id": "req-001",
  "method": "system.ping",
  "params": {},
  "client": {
    "source": "your-app",
    "protocol_version": "2.0.0",
    "trace_id": "trc-001"
  }
}

字段	类型	必填	说明
`request_id`	string	是	客户端生成的请求 ID
`method`	string	是	目标方法名
`params`	object	否	方法参数；未传时按空对象处理
`client`	object	否	调用方、协议版本、trace 等诊断信息

Response

json

{
  "request_id": "req-001",
  "code": 0,
  "message": "ok",
  "data": {},
  "ts": 1710000000
}

字段	类型	说明
`request_id`	string	对应请求 ID
`code`	number	稳定状态码，`0` 表示成功
`message`	string	简短说明
`data`	object	方法返回数据
`ts`	number	服务端时间戳

Event

服务端推送事件与请求响应使用不同 envelope：

json

{
  "event": "video.ready",
  "code": 0,
  "message": "ok",
  "payload": {
    "stream_id": "stream-1"
  },
  "ts": 1710000000
}

Video WS

对外 SDK 默认地址：

text

wss://sdk-runtime.localhost:18091?session_token=<session-token>&stream_id=<stream-id>

Video WS 连接参数：

参数	说明
`session_token`	`video.start` 返回的连接绑定 session token
`stream_id`	`video.start` 返回的视频流 ID

连接成功后服务端发送：

video.ready 文本事件
每帧一个 stream.frame_meta 文本事件
每帧一个 MJPEG/JPEG binary frame

Video WS 是输出通道。客户端不应向该通道发送控制命令；控制命令应继续走 Command WS。

自定义 TLS 域名时，Video WS 使用：

text

wss://<tls-host>:18091?session_token=<session-token>&stream_id=<stream-id>

session_token 与 stream_id 是 Video WS 的必需查询参数，在 ws 和 wss 连接中均不可省略。

常用错误码

错误码	名称	常见原因
`1000`	`INVALID_REQUEST`	请求不是合法 JSON 对象
`1001`	`INVALID_METHOD`	`method` 缺失或非法
`1002`	`INVALID_PARAMS`	必填参数缺失
`1003`	`UNSUPPORTED_METHOD`	方法未公开或未实现
`1004`	`RATE_LIMITED`	采集间隔未到；`capture.take` 响应的 `data.retry_after_ms` 为建议等待时间
`1100`	`AUTH_REQUIRED`	尚未创建连接绑定会话
`1101`	`TOKEN_INVALID`	API Key 无效
`1103`	`SESSION_TOKEN_INVALID`	session token 无效
`1105`	`DEVICE_NOT_IN_AUTH_SCOPE`	设备不在授权范围内
`1107`	`CAPABILITY_NOT_ALLOWED`	当前会话没有目标方法权限，或参数级能力超过当前权益等级
`1110`	`USAGE_LIMIT_EXCEEDED`	额度不足；trial 受限能力共享试用额度已耗尽
`1200`	`DEVICE_NOT_FOUND`	设备不存在
`1201`	`DEVICE_BUSY`	设备正被冲突操作占用；采集场景表示物理拍照动作正在执行
`1203`	`DEVICE_NOT_OPEN`	设备未打开
`1300`	`STREAM_NOT_FOUND`	stream 不存在或已关闭
`1901`	`PROVIDER_NOT_READY`	provider 未就绪
`1902`	`PROVIDER_CALL_FAILED`	provider 调用失败

更多错误码请参考错误码。

协议模型 ​

端点与 TLS ​

Command WS ​

Request ​

Response ​

Event ​

Video WS ​

常用错误码 ​

协议模型

端点与 TLS

Command WS

Request

Response

Event

Video WS

常用错误码