Device Live Link API#

POST /api/device/live is used to obtain the H5 player live link for a specified device. The API verifies device ownership and then returns a player URL that can be opened directly in a browser.

⚠️ Display Rules (MUST be strictly followed)#

The script outputs structured data in JSON format, which is the expected behavior. The display rules below are formatting instructions for the agent: the agent MUST parse the JSON output from the script, convert it into a user-friendly format according to the following rules before displaying it, and MUST NOT display the raw JSON directly.

The script output includes the _device_name field (device name), which is used for display.

1. When code == 0 and data contains live_url, MUST use Markdown link format:

📺 Live stream of "Living Room Camera":

▶️ Click to open live player

Key rules:

• Get the device name from _device_name and display it as "device name" instead of the MAC address
• If _device_name is empty, use the MAC address with the xxxxS_ prefix removed as a fallback
• live_url MUST be output using Markdown link syntax [text](url), and MUST NOT be output as bare URL text
• Use ▶️ Click to open live player as the link text

1. When code != 0, reply: "API call failed, error code {code}, reason: {message}"

Prerequisites#

The script depends on httpx. If it is not installed, the script will prompt python3 -m pip install httpx.

Configuration Declaration#

This skill depends on the following configuration items. The agent and user MUST confirm that they are correctly configured before running.

Required Configuration#

Configuration ItemDelivery MethodDescriptionAI_GATEWAY_API_KEY~/.openclaw/.env (persistent, written by OpenClaw clients), command line --api-key (temporary override)API key used for API authentication. CLI flag takes precedence over the file when both present

Optional Configuration#

Configuration ItemDelivery MethodDefault ValueDescriptionAI_GATEWAY_HOST~/.openclaw/.env``https://ai-open.icloseli.comGateway addressAI_GATEWAY_VERIFY_SSL~/.openclaw/.envtrueSet to false to disable TLS certificate verification (development environments only)

Configuration Source#

The script reads ~/.openclaw/.env as the single persistent configuration source. This file is shared by all skills and uses the format KEY=VALUE (one entry per line). OpenClaw clients write to this file when the user updates settings. The script does NOT read any AI_GATEWAY_* environment variables — env variables are intentionally ignored to avoid stale Gateway-process snapshots overriding the user's latest config.

Security Notes#

• The shared credential file ~/.openclaw/.env is readable by all skills under the same user. Ensure file permissions are restricted (e.g. chmod 600 ~/.openclaw/.env) and that only the OpenClaw service user has access. The IM clients write to this file under that user's home directory.
• TLS certificate verification is enabled by default. You MUST NOT disable it in production environments (disabling it introduces man-in-the-middle attack risks, and attackers may intercept API_KEY and device data)
• Before use, you MUST confirm that AI_GATEWAY_HOST points to a trusted domain
• You MUST use a least-privilege API_KEY to avoid reusing high-privilege credentials. This skill only requires permission to retrieve device live links

Network Access Declaration#

This skill only accesses the following endpoints (all under AI_GATEWAY_HOST):

EndpointMethodPurpose/api/device/listPOSTObtain device name mapping/api/device/livePOSTObtain device live link

The script does not access any other network resources.

Quick Start#

bash

python3 get_live_url.py --device-id "xxxxS_aabbccddeeff"

Request Format#

Request Body#

Parameter NameTypeRequiredDescriptiondevice_idstringYesDevice ID, format: xxxxS_<mac>, cannot be empty

Response Format#

json

{
  "code": 0,
  "message": "success",
  "request_id": "<32-character request trace ID>",
  "data": {
    "live_url": "https://example.com/h5player/pro/autoPlay_credentials.html?t=k7qp2vx9nb4ml8wr3ty6sa"
  },
  "_device_name": "Living Room Camera"
}

data Field#

Parameter NameTypeDescriptionlive_urlstringH5 player live link, which can be opened directly in a browser or WebView

Error Codes#

Error CodeHTTP Status CodeDescription1001401api_key not provided (missing Authorization header or incorrect format)1002401api_key is invalid or disabled2001400Missing required parameter ( device_id is empty, or the device does not belong to the current user)3001502Internal gateway service call failed5000500Internal error

Notes#

• device_id cannot be empty, otherwise error code 2001 is returned
• If the device does not belong to the current user, an error is returned directly
• IMPORTANT: device_id is case-sensitive. The prefix MUST be lowercase xxxxS_, NOT uppercase XXXXS_. The script will auto-correct the case, but the agent SHOULD always pass the correct lowercase format
• The returned live_url only contains a 22-character short-lived token (expires in 120 seconds by default). After the H5 player loads, it automatically calls /api/player/exchange to exchange it for the real playback credential. No sensitive information ( apiKey, productKey, stream token, deviceId) is included in the URL
• Global request timeout is 120 seconds