Connectivity

SDK Open uses two WebSocket channels:

• Command WS carries all JSON command requests and responses.
• Video WS only carries video output and stream-related events.

Business tokens are not passed in WebSocket handshake URLs. The client first connects Command WS anonymously, then binds a session by calling auth.create_session.

Connection Endpoints

Channel	Default external SDK connection	Plaintext compatibility endpoint	Purpose
Asset	https://sdk-runtime.localhost:18082	http://127.0.0.1:17082	Upload input files and read task assets.
Command WS	wss://sdk-runtime.localhost:18090	ws://127.0.0.1:17090	Send JSON requests and receive responses and events.
Video WS	wss://sdk-runtime.localhost:18091	ws://127.0.0.1:17091	Receive video output and stream events.

The external SDK package enables TLS by default and maps sdk-runtime.localhost to 127.0.0.1. Clients should use the HTTPS/WSS endpoints in the table. Plaintext HTTP/WS endpoints are for explicitly configured compatibility scenarios only and are not recommended for new integrations; an HTTPS page cannot connect to plaintext ws.

Video WS must retain the session_token and stream_id query parameters with either ws or wss. Command WS still does not put API keys, session tokens, or business parameters in its handshake URL.

TLS Configuration

The default external SDK configuration already enables SDK_TLS_ENABLED=1. To explicitly enable or adjust TLS in a custom deployment, provide a complete certificate chain and its matching private key:

Setting	Description
SDK_TLS_BIND_HOST	TLS listener address; defaults to the runtime bind_host.
SDK_TLS_CERT_FILE	PEM/fullchain file containing the server certificate and intermediate certificates.
SDK_TLS_KEY_FILE	Server PEM private-key file.
SDK_TLS_KEY_PASSWORD	Optional private-key password.
SDK_ASSET_HTTPS_PORT	Asset HTTPS port, default 18082.
SDK_COMMAND_WSS_PORT	Command WSS port, default 18090.
SDK_VIDEO_WSS_PORT	Video WSS port, default 18091.
SDK_ASSET_BASE_URL	Set to the client-reachable HTTPS asset base URL for remote, NAT, or DNS deployments.

The official package configures a local certificate and trusted root CA for sdk-runtime.localhost. Clients that use an independent certificate store must still import the applicable CA. TLS protects the transport only; it does not replace API keys, the auth.create_session session authentication, asset authorization, or network access controls. Admin and the local demo continue to use their existing HTTP ports.

1. Check the Runtime

If Admin HTTP is enabled, check runtime health first:

curl http://127.0.0.1:17080/healthz

The admin status endpoint requires an admin token:

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

2. Connect Command WS

With the default external SDK WSS connection:

wss://sdk-runtime.localhost:18090

After the connection is open, send system.ping:

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

Successful response:

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

3. Query Public Capabilities

Use system.capabilities to check exposed methods and the auth model:

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

The returned methods include public methods such as auth.create_session, device.list, device.open, device.close, video.start, and video.stop.

4. Connect Video WS

Video WS cannot be connected anonymously. Call video.start first to get session_token and stream_id, then use the default WSS connection:

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

For a custom TLS hostname, replace the host with one in the server certificate:

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

After the connection is accepted, the server sends a video.ready text event. Each frame then consists of:

• one stream.frame_meta text event
• one MJPEG/JPEG binary frame

Clients should decode binary frames as JPEG/MJPEG images according to stream.frame_meta.pixel_format=mjpeg, then draw the decoded image to Canvas. Render with a latest-frame-wins strategy to avoid latency when decoding or drawing is slower than the input frame rate.