连接建立

SDK Open 使用两个 WebSocket 通道：

• Command WS：承载所有 JSON 指令请求和响应。
• Video WS：只承载视频流输出和流相关事件。

业务 token 不放在 WebSocket 握手 URL 中。客户端先匿名建立 Command WS，再通过 auth.create_session 绑定会话。

连接端点

通道	对外 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	发送 JSON 请求、接收响应和事件。
Video WS	wss://sdk-runtime.localhost:18091	ws://127.0.0.1:17091	接收视频流和流事件。

对外 SDK 安装包默认开启 TLS，并将 sdk-runtime.localhost 映射到 127.0.0.1。客户端应优先使用上表中的 HTTPS/WSS 端点。明文 HTTP/WS 端点仅用于明确配置的兼容场景，不建议用于新的接入；在 HTTPS 页面中也不能连接明文 ws。

Video WS 无论使用 ws 还是 wss，都必须保留 session_token 与 stream_id 查询参数。Command WS 仍不在握手 URL 中携带 API Key、session token 或业务参数。

TLS 配置

对外 SDK 的默认配置已启用 SDK_TLS_ENABLED=1。如在自定义部署中显式启用或调整 TLS，请提供完整证书链和匹配私钥：

配置项	说明
SDK_TLS_BIND_HOST	TLS 监听地址；未设置时沿用运行时 bind_host。
SDK_TLS_CERT_FILE	包含服务端证书和中间证书的 PEM/fullchain 文件。
SDK_TLS_KEY_FILE	服务端 PEM 私钥文件。
SDK_TLS_KEY_PASSWORD	可选的私钥口令。
SDK_ASSET_HTTPS_PORT	Asset HTTPS 端口，默认 18082。
SDK_COMMAND_WSS_PORT	Command WSS 端口，默认 18090。
SDK_VIDEO_WSS_PORT	Video WSS 端口，默认 18091。
SDK_ASSET_BASE_URL	远程、NAT 或 DNS 部署时设置为客户端可访问的 HTTPS 资产基地址。

官方安装包会配置 sdk-runtime.localhost 的本机证书和受信任根 CA。使用独立证书库的客户端仍需导入相应 CA。TLS 仅保护传输链路，不能替代 API Key、auth.create_session 会话鉴权、资产访问鉴权和网络访问控制。Admin 与本地 Demo 继续使用其既有 HTTP 端口。

1. 检查运行时

如果 Admin HTTP 已启用，可先访问健康检查：

curl http://127.0.0.1:17080/healthz

管理状态接口需要管理 token：

curl -H "Authorization: Bearer <admin-token>" http://127.0.0.1:17080/api/status

2. 连接 Command WS

使用对外 SDK 默认的 WSS 连接：

wss://sdk-runtime.localhost:18090

连接成功后，可以先发送 system.ping：

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

成功响应：

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

3. 查询公开能力

使用 system.capabilities 可以确认当前运行时暴露的方法和授权模型：

{
  "request_id": "req-cap-001",
  "method": "system.capabilities",
  "params": {}
}

返回的 methods 会包含当前公开方法，例如 auth.create_session、device.list、device.open、device.close、video.start 和 video.stop。

4. 连接 Video WS

Video WS 不能直接匿名连接。必须先通过 video.start 获取 session_token 和 stream_id，再使用默认 WSS 连接：

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

如使用自定义 TLS 域名，将主机名替换为证书中的域名：

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

连接成功后，服务端会先发送 video.ready 文本事件，随后为每帧发送：

• 一个 stream.frame_meta 文本事件
• 一个 MJPEG/JPEG 二进制帧

客户端应根据 stream.frame_meta.pixel_format=mjpeg 将二进制帧按 JPEG/MJPEG 图像解码，再绘制到 Canvas。建议按最新帧优先策略渲染，避免视频帧堆积导致延迟。