Protocol Model

Endpoints and TLS

Channel	Default external SDK URL	Plaintext compatibility URL
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

The external SDK enables SDK_TLS_ENABLED=1 by default and maps sdk-runtime.localhost to 127.0.0.1. The default TLS ports are 18082, 18090, and 18091. Clients must trust the server certificate or its issuing CA; plaintext endpoints are for compatibility scenarios only. See Connectivity for TLS settings and certificate-chain and private-key requirements.

Command WS

Default external SDK URL:

wss://sdk-runtime.localhost:18090

Command WS carries JSON requests and responses. The handshake URL does not include API keys, session tokens, or business parameters.

For a custom TLS deployment, use wss://<tls-host>:18090, where <tls-host> must match the server certificate. With either ws or wss, clients submit the API key after connection through auth.create_session.

Request

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

Field	Type	Required	Description
request_id	string	Yes	Client-generated request ID
method	string	Yes	Target method name
params	object	No	Method parameters; omitted value is treated as an empty object
client	object	No	Source, protocol version, trace metadata, and diagnostics

Response

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

Field	Type	Description
request_id	string	Matching request ID
code	number	Stable status code. 0 means success
message	string	Short message
data	object	Method result data
ts	number	Server timestamp

Event

Server-pushed events use a separate envelope:

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

Video WS

Default external SDK URL:

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

Video WS query parameters:

Parameter	Description
session_token	Connection-bound session token returned by video.start
stream_id	Stream ID returned by video.start

After connection, the server sends:

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

Video WS is output-only. Clients should keep all control commands on Command WS.

For a custom TLS hostname, use:

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

session_token and stream_id are required Video WS query parameters with both ws and wss.

Common Error Codes

Code	Name	Common Cause
1000	INVALID_REQUEST	Request is not a valid JSON object
1001	INVALID_METHOD	method is missing or invalid
1002	INVALID_PARAMS	Required params are missing
1003	UNSUPPORTED_METHOD	Method is not public or not implemented
1004	RATE_LIMITED	Capture interval has not elapsed; data.retry_after_ms in a capture.take response gives the suggested delay
1100	AUTH_REQUIRED	No bound session exists
1101	TOKEN_INVALID	API key is invalid
1103	SESSION_TOKEN_INVALID	Session token is invalid
1105	DEVICE_NOT_IN_AUTH_SCOPE	Device is outside the authorized scope
1107	CAPABILITY_NOT_ALLOWED	The session lacks the target method capability, or the parameter-level feature exceeds the current entitlement tier
1110	USAGE_LIMIT_EXCEEDED	Quota exceeded; the shared trial quota for restricted features has been exhausted
1200	DEVICE_NOT_FOUND	Device does not exist
1201	DEVICE_BUSY	Device is occupied by a conflicting operation; for capture, a physical capture action is executing
1203	DEVICE_NOT_OPEN	Device is not open
1300	STREAM_NOT_FOUND	Stream does not exist or is already closed
1901	PROVIDER_NOT_READY	Provider is not ready
1902	PROVIDER_CALL_FAILED	Provider call failed

For more information, see Error Codes.