开发者与 API 指南

1. 开始使用

1.1 准备工作

步骤1。请确保网关已通电并正常工作。

步骤2。确保网关与电脑连接到同一局域网。然后在浏览器中输入CUBE的URL。

注意：如果您有多个网关，可以通过以下两种方式获取对应的IP地址以访问指定网关。

  1. 登录您的无线路由器并在DHCP中查看网关的IP地址。

  2. CUBE支持通过mDNS进行本地发现。

1.2 入门

  • 调用[获取访问令牌]接口，收到错误响应，提示点击 <完成>。注意，按下后，接口访问有效期不超过5分钟。

// 请求
curl --location --request GET 'http://<ip address>/open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json'

// 响应
{
  "error": 401,
  "data": {},
  "message": "link button not pressed" 
}

  • 点击 <完成> 并再次调用[获取访问令牌]接口。响应成功，获取到令牌。

  • 验证令牌。调用[获取设备列表]接口。响应成功，获取到设备列表。

  • 获取CUBE访问令牌方法：调用[获取访问令牌]接口后，CUBE Web控制台页面会弹出全局弹窗，提示用户确认获取接口调用凭证。

  • 注意：如果您同时打开多个CUBE Web控制台页面，确认弹窗会同时出现在多个控制台页面上，且在任一控制台页面上点击确认后，其他页面的弹窗将被关闭。

2. 核心概念

2.1 开发接口地址

网关Web API接口有两种访问方式（基于IP或域名），通常根路径为 /open-api/V2/rest/<具体功能模块>

// IP访问 http:///open-api/V2/rest/bridge

// 域名访问 http:///open-api/V2/rest/bridge

2.2 设备显示类别与能力

  • **设备显示类别 (DisplayCategory)。** 设备显示类别用于识别设备的具体类别，如开关、插座、灯等。 该信息将决定设备在网关中的界面显示效果.

  • **设备能力。** 设备能力用于描述设备的具体子功能，例如电源控制、亮度控制、色温控制等。 单个设备可以支持1个或多个能力.

    • capability： 描述能力名称，必须在全局唯一且为字符串类型。多个英文单词应以连字符（"-"）分隔。例如： "thermostat-target-setpoint".

    • name： 描述能力下的类别，也为字符串类型。多个英文单词应以连字符（"-"）分隔。例如： "auto-mode", "manual-mode".

    • permission： 描述与能力相关的权限，类型为字符串，按8421二进制编码格式。示例包括：

      • 设备可控： "1000"

      • 设备可配置： "0010"

      • 设备可控且可配置： "1010"

      • 设备可控且可上报： "1100"

各位的含义从右到左如下：ⅰ. 位0：允许查询设备 ⅱ. 位1：允许配置设备 ⅲ. 位2：允许设备上报数据 ⅳ. 位3：允许控制设备

settings： 描述该能力的配置项，类型为对象，并包含每个配置项的描述。 ⅰ. key： 描述配置项的名称，类型为字符串。多个英文单词应使用驼峰式表示。例如： "temperatureUnit". ⅱ. value： 描述配置项的内容。具体规范详见下表。

属性
类型
可选
说明

permission

string

否

描述该配置项的权限。

可选值：

  • 允许修改该配置项： "10"

  • 允许查看该配置项： "01"

  • 允许修改并查看该配置项： "11"

位说明：

  1. 位0： 允许查看该配置项

  2. 位1： 允许修改该配置项 | | 类型 | string | 否 | 描述配置项值的数据类型。 可选值：

  • "enum"

  • "numeric"

  • "object"

  • "boolean"

  • "string"

类型相关说明：

  1. 当 **type = enum**:

    • 将立即发出 value 字段（描述配置项值）在以下情况下为必填： permission 允许修改（"10" 或 "11").

    • 将立即发出 default （描述配置项的默认值）和 values （描述配置项的可选值）字段为可选。

  2. 当 **type = numeric**:

    • 将立即发出 value 字段在以下情况下为必填： permission 允许修改（"10" 或 "11").

    • 下列字段为可选：

      • min （描述配置项的最小值）

      • max （描述配置项的最大值）

      • step （描述配置项的步进值）

      • precision （描述精度）

      • unit （描述配置项的单位）

      • default （描述默认值）

  3. 当 **type = object**:

    • 将立即发出 value 字段在以下情况下为必填： permission 允许修改（"10" 或 "11").

    • 将立即发出 default 字段为可选。

  4. 当 **type = boolean**:

    • 将立即发出 value 字段在以下情况下为必填： permission 允许修改（"10" 或 "11").

    • 将立即发出 default 字段为可选。

  5. 当 **type = string**:

    • 将立即发出 value 字段在以下情况下为必填： permission 允许修改（"10" 或 "11").

    • 将立即发出 default 字段为可选。 |

3. Web API

数据类型

类型
说明

string

字符串数据类型。UTF8 编码。

number

数字数据类型。 双精度64位二进制格式 IEEE 754

int

整型数据类型。

object

对象数据类型。符合JSON的对象

string[]

字符串数组

int[]

整型数组

object[]

对象数组

bool

布尔值

date

时间字符串。ISO（ISO 8601 扩展格式）格式的字符串：YYYY-MM-DDTHH:mm:ss.sssZ。时区始终为UTC（协调世界时），以后缀“Z”标识。

通用响应结果

属性
类型
可选
说明

error

int

否

错误代码：

0：成功

400：参数错误

401：认证失败

500：服务器异常

data

object

否

响应数据体

message

string

否

响应描述：

当 error 等于 0 时，内容为 success

当 error 不等于 0 时，为非空字符串，内容为错误描述。

响应示例:

资源列表

类型
说明

支持的声音

- alert1（警报声音1）

  • alert2（警报声音2）

  • alert3（警报声音3）

  • alert4（警报声音4）

  • alert5（警报声音5）

  • doorbell1（门铃声音1）

  • doorbell2（门铃声音2）

  • doorbell3（门铃声音3）

  • doorbell4（门铃声音4）

  • doorbell5（门铃声音5）

  • alarm1（警报声音1）

  • alarm2（警报声音2）

  • alarm3（警报声音3）

  • alarm4（警报声音4）

  • alarm5（警报声音5） | | 支持的深度事件 | - bootComplete（系统启动完成）

  • networkConnected（网络已连接）

  • networkDisconnected（网络已断开）

  • systemShutdown（系统关机） -deviceDiscovered（发现设备）

  • system Armed（系统布防启用）

  • system Disarmed（系统撤防禁用）

  • factoryReset（恢复出厂设置） |

3.1 网关功能

a. 访问令牌

允许用户获取访问令牌。

  • 注意：设备重置后令牌将被清除。

  • 注意：获取到令牌后，需要再次按下按钮才能成功获取新令牌。

:::提示

  • URL：/open-api/V2/rest/bridge/access_token

  • 方法：GET

  • Header：

    • Content-Type: application/json ::: 请求参数：

属性

类型

可选

说明

app_name

string

是

应用名称说明。

成功的数据响应：

属性

类型

可选

说明

token

string

否

接口访问令牌。长期有效，请保存

app_name

string

是

应用名称说明。

:::提示 条件：用户触发<按键命令>并在有效时间内访问此接口。**状态码：**200 OK ::: 响应示例:

失败的数据响应：空对象 :::提示 条件：用户未触发<按键命令>，或有效时间已过期。**状态码：** 200 OK ::: 响应示例:

b. 获取网关状态

允许已授权用户通过此接口获取网关状态 :::提示

  • URL：/open-api/V2/rest/bridge/runtime

  • 方法：GET

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：无 成功的数据响应：

属性

类型

可选

说明

ram_used

int

否

内存使用百分比。[0-100]

cpu_used

int

否

CPU 使用百分比。[0-100]

power_up_time

date

否

最近一次开机时间

cpu_temp

int

否

CPU 温度：

单位：摄氏度

cpu_temp_unit

string

否

CPU 温度单位：

可选

values：'c', 'f'

sd_card_used

int

是

SD 卡使用率（百分比）：

范围：[0-100] 保留一位小数的精度

*注意：如果未插入SD卡或未格式化，则该值为空。

:::提示 条件：请求参数合法且通过用户身份验证。**状态码：**200 OK ::: 响应示例:

c. 设置网关

允许已授权用户通过此接口设置网关 :::提示

  • URL：/open-api/V2/rest/bridge/config

  • 方法：PUT

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：

属性

类型

可选

说明

volume

int

是

系统音量。[0-100]

成功的数据响应：空对象 {} :::提示 条件：请求参数合法且通过用户身份验证。**状态码：**200 OK ::: 响应示例:

d. 获取网关信息

允许已授权用户通过此接口获取网关信息 :::提示

  • URL：/open-api/V2/rest/bridge

  • 方法：GET

  • Header：

    • Content-Type: application/json ::: 请求参数：

属性

类型

可选

说明

ip

string

否

IP 地址

mac

string

否

MAC 地址

domain

string

是

网关服务域名

fw_version

string

否

固件版本

name

string

否

设备名称

成功的数据响应：空对象 {} :::提示 条件：无 **状态码：**200 OK ::: 响应示例:

e. 网关静音

允许已授权用户通过此接口将网关静音。 :::提示

  • URL：/open-api/v2/rest/bridge/mute

  • 方法：PUT

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::提示 条件：请求参数合法且通过用户身份验证。**状态码：**200 OK ::: 响应示例:

f. 解除网关静音

允许已授权用户通过此接口解除网关静音。 :::提示

  • URL：/open-api/v2/rest/bridge/unmute

  • 方法：PUT

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::提示 条件：请求参数合法且通过用户身份验证。**状态码：**200 OK ::: 响应示例:

g. 取消网关告警

允许已授权用户通过此接口禁用网关上的告警声音状态。 :::提示

  • URL：/open-api/v2/rest/bridge/cancel_alarm

  • 方法：PUT

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::提示 条件：请求参数合法且通过用户身份验证。**状态码：**200 OK ::: 响应示例:

3.2 硬件功能

a. 重启网关

允许已授权用户通过此接口重启网关 :::提示

  • URL：/open-api/V2/rest/hardware/reboot

  • 方法：POST

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::提示 条件：请求参数合法且通过用户身份验证。**状态码：**200 OK :::

b. 扬声器控制

允许已授权用户通过此接口控制扬声器 :::提示

  • URL：/open-api/V2/rest/hardware/speaker

  • 方法：POST

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：

属性

类型

可选

说明

type

string

否

可选参数：1.play_sound（播放声音） 2.play_beep（播放蜂鸣）

sound

SoundObject

是（若 type 为 play_sound 则为否）

声音对象。

beep

BeepObject

是（若 type 为 play_beep 则为否）

蜂鸣对象

SoundObject

属性

类型

可选

说明

name

string

否

声音名称。支持的值可在[资源列表 - 支持的声音]中查看

volume

int

否

声音音量。[0-100]

countdown

int

否

扬声器播放声音的持续时间，时间结束后会自动停止播放。单位：秒。[0,1799]

BeepObject

属性

类型

可选

说明

name

string

否

深度事件名称。支持的值可在[资源列表 - 支持的深度事件]中查看

volume

int

否

深度事件音量。[0-100]

成功的数据响应：空对象 {} :::提示 条件：请求参数合法且通过用户身份验证。**状态码：** 200 OK ::: 响应示例:

3.3 设备管理功能

a. 支持的设备类型

设备类型

取值

iHost 版本

插座

plug

≥ 2.1.0

开关

switch

≥ 2.1.0

灯

light

≥ 2.1.0

窗帘

curtain

≥ 2.1.0

门/窗传感器

contactSensor

≥ 2.1.0

人体感应传感器

motionSensor

≥ 2.1.0

温度传感器

temperatureSensor

≥ 2.1.0

湿度传感器

humiditySensor

≥ 2.1.0

温湿度传感器

temperatureAndHumiditySensor

≥ 2.1.0

漏水探测器

waterLeakDetector

≥ 2.1.0

烟雾探测器

smokeDetector

≥ 2.1.0

无线按钮

button

≥ 2.1.0

摄像头

camera

≥ 2.1.0

通用传感器

sensor

≥ 2.1.0

通用传感器

sensor

≥ 2.1.0

风扇灯

fanLight

≥ 2.1.0

空调

airConditioner

≥ 2.1.0

风扇

fan

≥ 2.1.0

恒温器

thermostat

≥ 2.1.0

b. 支持的设备能力

电源开关（power）：

功能声明示例：

状态属性：

协议（查询状态与控制指令）：

打开：

关闭：

通道切换（toggle）：

功能声明示例：

单组件示例：

多组件示例：

状态属性：

协议（查询状态与控制指令）：

切换格式：

通道点动（toggle-inching）：

功能声明示例：

状态属性

无

协议（查询状态与控制指令）

无

亮度调节（brightness）：

功能声明示例：

状态属性：

协议（查询状态与控制指令）：

将亮度设置为 80%。（0 最暗，100 最亮。）

色温调节（color-temperature）：

功能声明示例：

状态属性：

协议（查询状态与控制指令）：

将色温调整为 50%：

颜色调节（color-rgb）：

功能声明示例：

状态属性：

协议（查询状态与控制指令）：

设置颜色为紫色：

百分比调节（percentage）：

功能声明示例：

状态属性：

协议（查询状态与控制指令）：

调整到 40%：

电机控制（motor-control）：

功能声明示例：

状态属性：

协议（查询状态与控制指令）：

打开电机：

电机反转（motor-reverse）：

功能声明示例：

状态属性：

协议（查询状态与控制指令）：

设置电机为正转：

电机校准（motor-clb）

功能声明示例：

属性（状态）：

协议（状态上报）：

上报电机状态为正在校准：

上电状态（startup）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

设置上电状态为始终开启：

唤醒激活（identify）

功能声明示例：

属性（状态）：

协议（状态上报与控制指令）：

设置唤醒激活时间：

上报激活状态：

实时能耗统计开关（power-consumption）

功能声明示例：

属性（状态）：

开始/停止实时统计：

按时间范围查询能耗：

在时间范围内返回统计结果：

协议（状态上报与控制指令）：

开始实时统计：

停止实时统计：

获取历史能耗：

获取实时能耗：

温湿模式检测（thermostat-mode-detect）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

格式：

示例：

恒温器模式（thermostat-mode）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

恒温器自适应恢复状态（thermostat/adaptive-recovery-status）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

恒温器目标温度设置（thermostat-target-setpoint）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

传感器检测（detect）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

温度检测（temperature）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

湿度检测（humidity）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

电量检测（battery）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

单按钮检测（press）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

多按钮检测（multi-press）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

信号强度检测（rssi）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

防拆检测（tamper-alert）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

照度等级检测（illumination-level）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

电压检测（voltage）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

电流检测（electric-current）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

电功率检测（electric-power）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

故障检测（fault）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

阈值触发器（threshold-breaker）

功能声明示例：

属性（状态）

  • 无

协议（查询状态与控制指令）

  • 无

点动功能（inching）

功能声明示例：

属性（状态）：

  • 无

协议（查询状态与控制指令）：

  • 无

摄像头流（camera-stream）

功能声明示例：

属性（状态）：

  • 无

协议（查询状态与控制指令）：

  • 无

模式控制（mode）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

二氧化碳检测（co2）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

照度检测（illumination）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

烟雾检测（smoke）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

门磁开关检测（contact）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

运动检测（motion）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

漏水检测（water-leak）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

窗户检测开关（window-detection）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

童锁开关（child-lock）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

防直吹开关（anti-direct-blow）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

水平摆风开关（horizontal-swing）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

垂直摆风开关（vertical-swing）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

ECO 模式开关（eco）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

切换启动（toggle-startup）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

检测保持（detect-hold）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

切换识别/激活（toggle-identify）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

切换电压检测（toggle-voltage）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

子组件电流检测（toggle-electric-current）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

子组件功率检测（toggle-electric-power）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

子组件用电量统计（toggle-power-consumption）

功能声明示例：

属性（状态）：

开始/停止实时统计：

按时间范围查询能耗：

指定时间范围内的用电响应：

协议（查询状态与控制指令）：

开始实时统计：

停止实时统计：

获取历史能耗：

获取实时能耗：

链路质量指示（lqi）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

功能配置（configuration）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

系统（system）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

湿度（moisture）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

气压（barometric-pressure）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

风速（wind-speed）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

风向（wind-direction）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

降雨量（rainfall）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

紫外线指数（ultraviolet-index）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

电导率（electrical-conductivity）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

发射功率（transmit-power）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

PM2.5 检测（pm25）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

VOC 指数（voc-index）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

天然气检测（gas）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

灌溉工作状态（irrigation/work-status）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

工作状态上报：

工作状态查询：

工作状态查询结果：

灌溉工作模式（irrigation/work-mode）

功能声明示例：

属性（状态）：

协议（查询状态与控制指令）：

自动灌溉控制器（irrigation/auto-controller）

功能声明示例：

属性（状态）：

单次或循环定时：

单次或循环定量：

协议（查询状态与控制指令）：

单次或循环定时：

单次或循环定量：

支持的预设模式

**模式名称 **
**可选值 **

风扇等级（fanLevel）

"low"

"medium"

"high"

恒温器模式（thermostatMode）

"auto"

"manual"

空调模式 >= 1.11.0（airConditioner Mode）

"cool"

"heat"

"auto"

"fan"

"dry"

风扇模式 >= 1.11.0（Fan Mode）

"normal"

"sleep"

"child"

水平角度 >= 1.11.0（Horizontal Angle）

"30"

"60"

"90"

"120"

"180"

"360"

垂直角度 >= 1.11.0（Vertical Angle）

"30"

"60"

"90"

"120"

"180"

"360"

c. 标签说明

  • 特殊键 toggle 用于设置 toggle 子组件的名称。

  • 特殊键 temperature_unit 用于设置温度单位。

d. 特殊错误代码及说明

错误代码

说明

iHost 版本

110000

对应 id 的子设备/组不存在

≥2.1.0

110001

网关处于发现 zigbee 设备的状态

≥2.1.0

110002

组内设备没有共同的能力

≥2.1.0

110003

设备数量不正确

≥2.1.0

110004

组数量不正确

≥2.1.0

110005

设备离线

≥2.1.0

110006

更新设备状态失败

≥2.1.0

110007

更新组状态失败

≥2.1.0

110008

已达到最大组数。最多可创建 50 个组

≥2.1.0

110009

摄像头设备的 IP 地址不正确

≥2.1.0

110010

摄像头设备访问授权错误

≥2.1.0

110011

摄像头设备流地址错误

≥2.1.0

110012

摄像头设备视频编码不受支持

≥2.1.0

110013

设备已存在

≥2.1.0

110014

摄像头不支持离线操作

≥2.1.0

110015

账户密码与 RTSP 流地址中的账户密码不一致

≥2.1.0

110016

网关处于发现 onvif 摄像头的状态

≥2.1.0

110017

超出可添加摄像头的最大数量

≥2.1.0

110018

ESP 摄像头的路径错误

≥2.1.0

110019

访问第三方设备服务地址失败

≥2.1.0

e. 搜索子设备

允许授权用户通过此接口启用或禁用网关搜索子设备

  • 💡注意：目前仅支持搜索 Zigbee 子设备。

  • 💡注意：Zigbee 子设备搜索后会自动添加。无需使用 “手动添加子设备” 接口 :::tips

  • URL：/open-api/V2/rest/devices/discovery

  • 方法: PUT

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：

属性

类型

可选

说明

enable

boolean

否

true（开始配对）；false（暂停配对）

type

string

否

搜索类型：Zigbee

成功的数据响应：空对象 {} :::提示 条件：请求参数合法且通过用户身份验证。**状态码：** 200 OK ::: 响应示例:

f. 手动添加子设备

允许授权用户通过此接口添加一个 单个 子设备。

  • 注意：目前仅支持 RTSP 摄像头和 ESP32 摄像头 :::tips

  • URL：/open-api/V2/rest/devices

  • 方法：POST

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：

属性

类型

可选

说明

name

string

否

子设备名称

display_category

string

否

设备类型。仅支持 camera。

capabilities

CapabilityObject[]

否

能力列表。当 display_category = camera 时，capabilities 仅包含 camera-stream 能力。

protocal

string

否

设备协议。RTSP；ESP32-CAM

manufacturer

string

否

制造商。

model

string

否

设备型号

firmware_version

string

否

设备固件版本

CapabilityObject

属性

类型

可选

说明

capability

string

否

能力名称。仅支持 "camera-stream"

permission

string

否

设备权限。仅支持只读。

configuration

CameraStreamConfigurationObject

是

摄像头流配置。

SettingsObject

属性

类型

可选

说明

streamSetting

StreamSettingObject

否

流服务配置

StreamSettingObject

属性

类型

可选

说明

type

string

否

流服务配置

permission

string

否

能力权限。仅支持 "11"（可修改）。

value

StreamSettingValueObject

否

具体配置值

StreamSettingValueObject

属性

类型

可选

说明

stream_url

string

否

流 URL 格式

格式：<schema>://<hostname>:<port>/<username>:<password>@<service_path>

示例：rtsp://admin:[email protected]:554/streaming/channel01

Schema 选项：

rtsp （实时流传输协议）

http （超文本传输协议）— 适用于 ESP32-CAM 设备

*注意：有些摄像头可能不需要用户名或密码。在这种情况下，你可以从 URL 中省略 <username> 和 <password> 字段。

成功的数据响应：

属性

类型

可选

说明

serial_number

string

否

设备唯一序列号

:::提示 条件：请求参数合法且通过用户身份验证。**状态码：**200 OK ::: 响应示例:

失败数据响应：空对象 :::tips 条件：

  1. 摄像头流地址访问错误（格式错误、授权失败、网络异常等）

  2. 设备已存在

  3. 若单个设备添加失败，则返回所有设备添加失败。

状态码: 200 OK 错误代码： ● 110009 摄像头 IP 地址错误 ● 110010 摄像头访问授权错误 ● 110011 摄像头流地址错误 ● 110012 摄像头视频编码不支持 ● 110013 设备已存在 ::: 响应示例:

g. 获取子设备列表

允许授权用户通过此接口获取网关子设备列表。 :::tips

  • URL：/open-api/V2/rest/devices

  • 方法: GET

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：无 成功的数据响应：

属性

类型

可选

说明

device_list

ResponseDeviceObject[]

否

设备列表

ResponseDeviceObject

属性

类型

可选

说明

serial_number

string

否

设备唯一序列号

third_serial_number

string

"N" 表示连接第三方设备，否则为 "Y"

第三方设备唯一序列号

service_address

string

"N" 表示连接第三方设备，否则为 "Y"

第三方服务地址

name

string

否

设备名称，若未重命名，前端将根据默认显示规则显示。

manufacturer

string

否

制造商

model

string

否

设备型号

firmware_version

string

否

固件版本。可以为空字符串。

hostname

string

是

设备主机名

mac_address

string

是

设备 MAC 地址

app_name

string

是

所属应用的名称。如果在获取开放接口证书时填写了 app_name，则随后通过该证书连接的所有设备都会写入此字段。

display_category

string

否

设备分类

capabilities

CapabilityObject[]

否

设备能力

protocol

string

"N" 表示连接第三方设备，否则为 "Y"

设备协议：zigbee、onvif、rtsp、esp32-cam

state

object

是

设备状态对象。有关不同能力的状态示例，请查看【支持的设备能力】

tags

object

是

JSON 格式的键值，自定义设备信息。其功能如下：- 用于存储设备通道- 用于存储温度单位- 其他第三方设备的自定义信息

在线

boolean

否

在线状态：True 表示在线False 表示离线

子网

boolean

是

是否与网关处于同一子网

CapabilityObject 💡注意：请查看[支持的设备能力]的示例以了解受支持的设备能力。

属性

类型

可选

说明

capability

string

否

能力名称。详情请查看[支持的设备能力]

permission

string

否

能力权限。可能的值为 "read"（可读）、"write"（可写）、"readWrite"（可读写）。

configuration

object

是

能力配置信息。目前用于 camera-stream，详见[支持的设备能力]

name

string

是

toggle 中的 name 字段。用于标识多通道设备的子通道号。例如，name 为 1 则表示通道 1。

:::提示 条件：请求参数合法且通过用户身份验证。**状态码：**200 OK ::: 响应示例:

h. 更新指定设备信息或状态

允许授权用户通过此接口修改子设备的基本信息并发出控制命令。 :::tips

  • URL：/open-api/V2/rest/devices/{serial_number}

  • 方法：PUT

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：

属性

类型

可选

说明

name

string

是

设备名称

tags

object

是

JSON 格式的键值，自定义设备信息。

state

object

是

设备状态对象。有关不同能力的状态示例，请查看[支持的设备能力]

configuration

object

是

能力配置信息，目前仅 camera_stream 能力支持修改。

数据响应成功： :::tips 条件： 请求参数合法，且用户身份验证通过。**状态码：**200 OK 错误代码:

  • 110000 与 id 对应的子设备/分组不存在 ::: 响应示例:

i. 删除子设备

允许授权用户通过此接口删除子设备。 :::tips

  • URL：/open-api/V2/rest/devices/{serial_number}

  • 方法：DELETE

  • Header：

    • Content-Type: application/json

    • 授权：Bearer ::: 请求参数：

属性

类型

可选

说明

name

string

是

设备名称。

tags

object

是

以 JSON 格式的键值对，用于存储子设备的通道名称及其他信息。

state

object

是

改变设备状态；具体协议细节请参阅“支持的设备能力”。

capabilities

CapabilityObject []

是

能力配置信息；所有支持设置配置的能力均可修改。注意权限不可更改。

数据响应成功： :::tips 条件： 请求参数合法，且用户身份验证通过。**状态码：**200 OK 错误代码：

  • 110000：与 ID 对应的子设备/分组不存在。

  • 110006：更新设备状态失败。

  • 110019：访问第三方设备服务地址失败。

  • 110024：更新设备配置失败。 ::: 响应示例:

j. 删除子设备

允许授权用户通过此接口删除子设备。 :::tips

  • URL：/open-api/v2/rest/devices/{serial_number}

  • 方法：DELETE

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：无 成功数据响应： :::tips 条件：请求参数合法且通过用户身份验证。**状态码：**200 OK ::: 响应示例:

k. 查询设备状态

允许授权用户通过此接口查询设备状态。 :::tips

  • URL：/open-api/v2/rest/devices/:serial_number/query-state/{capability}

  • 方法：POST

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：

属性

类型

可选

说明

query_state

object

否

查询设备状态；具体协议细节请参阅“支持的设备能力”。

数据响应成功： :::tips 条件：请求参数合法且通过用户身份验证。**状态码：**200 OK ::: 响应示例:

3.4 安防管理

a. 获取安防列表

允许授权用户通过此接口修改网关设置。 :::tips

  • URL：/open-api/v2/rest/security

  • 方法：GET

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：无 成功数据响应：

属性

类型

可选

说明

security_list

ResponseSecurityObject[]

否

响应设备列表

ResponseDeviceObject

属性

类型

可选

说明

sid

int

否

安防 id

name

string

否

安防名称

enable

bool

否

是否启用

  • true 启用

  • false 禁用 |

:::提示 条件：请求参数合法且通过用户身份验证。**状态码：**200 OK ::: 响应示例:

b. 启用指定安防模式

允许授权用户通过此接口启用指定的安防模式。 :::tips

  • URL：/open-api/v2/rest/security/{security_id}/enable

  • 方法：PUT

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：无 成功数据响应：空对象 {} :::tips 条件：请求参数合法且通过用户身份验证。**状态码：**200 OK ::: 响应示例:

c. 禁用指定安防模式

允许授权用户通过此接口禁用指定的安防模式。 :::tips

  • URL：/open-api/v2/rest/security/{security_id}/disable

  • 方法：PUT

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：无 成功数据响应：空对象 {} :::tips 条件：请求参数合法且通过用户身份验证。**状态码：**200 OK ::: 响应示例:

d. 一键启用安防设置

允许授权用户通过此接口启用一键安防设置模式。 :::tips

  • URL：/open-api/v2/rest/security/enable

  • 方法：PUT

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：无 成功数据响应：空对象 {} :::tips 条件：请求参数合法且通过用户身份验证。**状态码：**200 OK ::: 响应示例:

e. 禁用安防

允许授权用户通过此接口禁用安防。 :::tips

  • URL：/open-api/v2/rest/security/disable

  • 方法：PUT

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：无 成功数据响应：空对象 {} :::tips 条件：请求参数合法且通过用户身份验证。**状态码：**200 OK ::: 响应示例:

4. 第三方设备接入

4.1 接入说明

设备接入

1.0.jpg

第三方网关接入

2.0.jpg

接入步骤

  1. 确定设备在网关中的分类。详情请查看[支持的设备类型]。

  2. 确定设备可以接入的能力。详情请查看[支持的设备能力]。

  3. 调用[Discovery Request] 接口将设备添加到网关。

    1. 注意：您需要提供用于接收网关下发指令的服务地址，用于接收网关发出的设备控制指令.

  4. 若第三方设备状态发生变化，需要调用[Device States Change Report] 接口将最新状态上报给网关。

  5. 添加后，第三方设备将出现在设备列表中，并具有网关的大部分功能（与其他非第三方设备类似）。与设备相关的常用开放接口可正常使用。

  • 选择合适的设备类别。分类会影响设备连接到网关后 UI 的最终显示效果。

  • 选择正确的设备能力。能力列表将决定设备状态协议的内容。

编程流程

a. 设备接入

3.0.jpg

b. 第三方网关接入

4.0.jpg

4.2 接入示例

开关、插座

同步第三方设备

上报设备状态

上报离线/在线

接收关于网关控制设备的指令

查询设备

4.3 Web API

第三方请求网关接口

请求格式

允许授权用户通过此接口向网关发送事件请求。 :::tips

  • URL：/open-api/V2/rest/thirdparty/event

  • 方法：POST

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：

属性

类型

可选

说明

event

EventObject

否

请求事件对象结构信息

EventObject

属性

类型

可选

说明

header

HeaderObject

否

请求头结构信息

endpoint

EndpointObject

是

请求 endpoint 结构信息 注意：当同步新设备列表时该字段为空。

payload

PayloadObject

否

请求负载结构信息

HeaderObject

属性

类型

可选

说明

name

string

否

请求名称。可选参数：DiscoveryRequest：同步新设备 DeviceStatesChangeReport：设备状态更新上报 DeviceOnlineChangeReport：设备在线状态上报

message_id

string

否

请求消息 ID，UUID_V4

version

string

否

请求协议版本号。目前固定为 1

EndpointObject

属性

类型

可选

说明

serial_number

string

否

设备唯一序列号

third_serial_number

string

否

第三方设备唯一序列号

tags

object

是

JSON 格式的键值，自定义设备信息。[设备管理功能] - [标签说明]

PayloadObject 根据不同的 header.name 有不同的请求结构。

响应格式

:::tips **状态码：**200 OK 响应参数： :::

属性

类型

可选

说明

header

HeaderObject

否

响应头结构信息

payload

PayloadObject

否

响应负载结构信息

HeaderObject

属性

类型

可选

说明

name

string

否

响应头名称。可选参数：Response：成功响应 ErrorResponse：错误响应

message_id

string

否

响应头消息 ID，UUID_V4。在此处传入请求消息 header.message_id *如果请求输入参数缺少 message_id，则响应时该字段将为空字符串。

version

string

否

- 请求协议版本号。目前固定为 1。

成功响应--PayloadObject ：

根据请求类型，响应结构不同。详情请参考具体的请求说明文档。

失败响应--PayloadObject：

属性

类型

可选

说明

type

string

否

错误类型：

  • INVALID_PARAMETERS：参数错误

  • AUTH_FAILURE：鉴权错误

  • INTERNAL_ERROR：内部服务错误 | | description | string | N | 错误描述 |

DiscoveryRequest 同步新的设备列表

  • 注意：设备同步至网关后默认处于在线状态，即 online=true。后续在线状态的变化完全依赖第三方通过 DeviceOnlineChangeReport 接口的同步。

请求参数： EndpointObject**：**无 PayloadObject：

属性

类型

可选

说明

endpoints

EndpointObject[]

否

设备列表

EndpointObject：

属性

类型

可选

说明

third_serial_number

string

否

第三方设备唯一序列号

name

string

否

设备名称

display_category

string

否

设备类别。详情见[支持的设备类型]。*第三方设备目前不支持添加摄像头。

capabilities

CapabilityObject[]

否

能力列表

state

object

否

初始状态信息

manufacturer

string

否

制造商

model

string

否

设备型号

tags

object

是

JSON 格式的键值，自定义设备信息：用于存储设备通道用于存储温度单位其他第三方自定义数据

firmware_version

string

否

固件版本

service_address

string

否

服务地址。例如 http://192.168.31.14/service_address

请求示例：

响应参数： PayloadObject：

属性

类型

可选

说明

endpoints

EndpointObject[]

否

设备列表

EndpointObject：

属性

类型

可选

说明

serial_number

string

否

设备唯一序列号

third_serial_number

string

否

第三方设备唯一序列号

正确响应示例：

错误响应示例：

DeviceStatesChangeReport 设备状态变更上报

  • 注意：重复的状态上报可能误触发关联场景。

请求参数： PayloadObject：

属性

类型

可选

说明

state

object

否

设备状态，详情见[支持的设备能力]

请求示例：

响应参数： PayloadObject：空对象 成功响应示例：

DeviceOnlineChangeReport 设备在线状态上报

  • 注意：重复的状态上报可能误触发关联场景。

请求参数： PayloadObject：

属性

类型

可选

说明

在线

boolean

否

设备在线状态 true：在线

false：离线

请求示例：

响应参数： PayloadObject：空对象 成功响应示例：

DeviceInformationUpdatedReport 设备信息更新上报

  • 注意：更新可能会影响已存在的场景或安防功能。

请求参数： PayloadObject：

属性

类型

可选

说明

capabilities

| CapabilityObject[]

| N

| 能力列表。详情见支持的设备能力部分。**注意：**该参数仅会更新 value 的 设置 键位于 CapabilityObject内，并且仅在 permission 的情况下允许更新 设置 键为 11 或 01。有关 设置 在 CapabilityObject中的具体结构定义，请参见第 2.3 节 设备显示类别与设备能力 的详细说明。 | | tags

| object

| Y

| JSON 格式的键值，自定义设备信息。

  • 可用于存储设备通道

  • 可用于存储温度单位

  • 其他第三方自定义数据 |

请求示例：

响应参数： PayloadObject：空对象 成功响应示例：

网关通过设备服务地址向指令接口发送指令

  • 注意：

  1. 第三方需在 3 秒内响应网关的请求，否则网关会判定命令处理超时。

  2. 若第三方服务离线，网关会将设备置为离线状态，第三方服务需通过上报设备状态（DeviceStatesChangeReport）或在线状态（DeviceOnlineChangeReport）才能恢复为在线状态。

请求格式

网关通过设备服务地址接口向第三方下发指令。 :::tips

  • URL：

  • 方法：POST

  • Header：

    • Content-Type: application/json ::: 请求参数：

属性

类型

可选

说明

directive

DirectiveObject

否

指令对象结构信息

DirectiveObject

属性

类型

可选

说明

header

HeaderObject

否

请求头结构信息

endpoint

EndpointObject

否

请求 endpoint 结构信息

payload

PayloadObject

否

请求负载结构信息

HeaderObject

属性

类型

可选

说明

name

string

否

请求名称。可选参数：UpdateDeviceStates：更新设备状态

message_id

string

否

请求消息 ID，UUID_V4

version

string

否

请求协议版本号。目前固定为 1。

EndpointObject

属性

类型

可选

说明

serial_number

string

否

设备唯一序列号

third_serial_number

string

否

第三方设备唯一序列号

tags

object

否

JSON 格式的键值，自定义设备信息。[设备管理功能] - [标签说明]

PayloadObject：根据不同的 header.name，每种都有具体的请求结构。

请求示例：

响应格式

:::tips **HTTP 状态码：**200 OK HTTP 响应属性： :::

属性

类型

可选

说明

event

EventObject

否

响应事件结构信息

EventObject

属性

类型

可选

说明

header

HeaderObject

否

请求头结构信息

payload

PayloadObject

否

请求负载结构信息

HeaderObject

属性

类型

可选

说明

name

string

否

响应头名称。可选参数：UpdateDeviceStatesResponse：更新设备状态响应 ErrorResponse：错误响应

message_id

string

否

响应头消息 ID，UUID_V4。传入请求消息 header.message_id

version

string

否

请求协议版本号。目前固定为 1。

成功响应--PayloadObject：

根据请求类型，响应结构不同。详情请参考具体的请求说明文档。

失败响应--PayloadObject：

属性

类型

可选

说明

type

string

否

错误类型:

  • ENDPOINT_UNREACHABLE：设备不可达或离线

  • ENDPOINT_LOW_POWER：设备处于低电量模式，无法被控制

  • INVALID_DIRECTIVE：来自网关的指令异常

  • NO_SUCH_ENDPOINT：设备不存在

  • NOT_SUPPORTED_IN_CURRENT_MODE：当前模式不支持该操作

  • INTERNAL_ERROR：内部服务错误

  • REMOTE_KEY_CODE_NOT_LEARNED：遥控器按键码未学习 |

:::提示 条件： 请求参数合法。**状态码：**200 OK 响应参数： :::

UpdateDeviceStates

请求参数： PayloadObject：

属性

类型

可选

说明

state

object

否

设备状态，详情见[支持的设备能力]。

请求示例：

响应参数： PayloadObject：空对象 成功响应示例

QueryDeviceStates

请求参数： PayloadObject：

属性

类型

可选

说明

state

object

否

设备状态，详情见[支持的设备能力]。

请求示例：

响应参数： PayloadObject：

属性

类型

可选

说明

state

object

否

设备状态，详情见[支持的设备能力]。

响应示例：

ConfigureDeviceCapabilities

请求参数： PayloadObject：

属性

类型

可选

说明

capabilities

CapabilityObject[]

否

能力列表。详情可见支持的设备能力部分。注意，permission 字段不可更改，同步时传入相同的值即可。

请求示例：

响应参数： PayloadObject：空对象 成功响应示例

5. 服务端推送事件

MDN EventSource 接口说明：https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events

5.1 指令

网关支持使用 SSE（Server-sent events）向客户端推送消息。客户端在获取访问凭证后可以监听 SSE 消息，并在收到网关推送的消息后按照开发接口事件通知协议解析推送消息内容。需要注意的是，网关当前使用 HTTP1.1 协议，因此浏览器端的 SSE 连接会有最多不超过 6 个连接的限制（具体说明见 MDN EventSource 接口说明）。

5.2 通用格式

:::提示

  • URL：/open-api/V2/sse/bridge

  • 方法：GET ::: 请求参数：

名称
类型
可选
说明

access_token

string

否

访问令牌

注意：在请求 SSE 连接时，网关会校验 access_token，若无效将返回鉴权失败错误。{ "error": 401, "data": {}, "message": "invalid access_token"}

## 例如：模块名：device 版本：1,v2,v3 消息类型：addDevice

示例：

5.3 设备模块

a. 添加设备事件

:::tips 模块名：device 版本：v2 消息类型：addDevice event.data 参数： :::

名称
类型
可选
说明

payload

ResponseDeviceObjectObject - 与获取设备列表接口相同

否

设备信息

示例：

b. 更新设备状态事件

:::tips 模块名：device 版本：v2 消息类型：updateDeviceState event.data 参数： :::

名称
类型
可选
说明

endpoint

EndpointObject

否

设备信息

payload

对象。结构与设备状态相同

否

设备状态数据

EndpointObject：

参数
类型
可选
说明

serial_number

string

否

设备唯一序列号

third_serial_number

string

是

第三方设备的唯一序列号。对于通过开放接口接入的设备，该字段为必填项。

示例：

c. 更新设备信息事件

:::tips 模块名：device 版本：v2 消息类型：updateDeviceInfo event.data 参数： :::

名称
类型
可选
说明

endpoint

EndpointObject

否

设备信息

payload

DeviceChangeObject

否

设备变更数据

EndpointObject：

属性
类型
可选
说明

serial_number

string

否

设备唯一序列号

third_serial_number

string

是

第三方设备的唯一序列号。对于通过开放接口接入的设备，该字段为必填项。

DeviceChangeObject

名称
类型
可选
说明

name

string

否

设备名称

capabilities

CapabilityObject []

是

设备能力列表。

tags

object

是

tagsobject | 可为空 | 用于自定义设备信息的 JSON 格式键值对。

  • 可用于存储设备通道。

  • 可用于存储温度单位。

  • 用于其他第三方自定义数据。 |

示例：

d. 删除设备事件

:::tips 模块名：device 版本：v2 消息类型：deleteDevice event.data 参数： :::

** 名称 **
** 类型 **
** 可选**
** 描述 **

endpoint

EndpointObject

否

设备信息

EndpointObject：

属性
类型
可选
说明

serial_number

string

否

设备唯一序列号

third_serial_number

string

是

第三方设备的唯一序列号。对于通过开放接口接入的设备，该字段为必填项。

示例：

e. 更新设备在线事件

:::tips 模块名：device 版本：v2 消息类型：updateDeviceOnline event.data 参数： :::

名称
类型
可选
说明

endpoint

EndpointObject

否

设备信息

payload

DeviceChangeObject

否

设备变更数据

EndpointObject：

属性
类型
可选
说明

serial_number

string

否

设备唯一序列号

third_serial_number

string

是

第三方设备的唯一序列号。对于通过开放接口接入的设备，该字段为必填项。

DeviceChangeObject

名称
类型
可选
说明

在线

boolean

否

设备在线状态

示例：

5.4 网关模块

a. 安防状态更新事件

:::tips 模块名：device 版本：v2 消息类型：updateDeviceOnline event.data 参数： :::

属性

类型

可选

说明

payload

SecurityStateObject

否

设备信息

SecurityStateObject

属性

类型

可选

说明

告警状态

string

否

  • 布防状态 | 已布防

  • 撤防状态 | 已撤防 |

示例：

5.5 安防模块

a. 布防状态更新事件

:::tips 模块名：device 版本：v2 消息类型：updateDeviceOnline event.data 参数： :::

属性

类型

可选

说明

payload

ArmStateObject

否

布防和撤防信息

ArmStateObject：

属性

类型

可选

说明

arm_state

string

否

  • 布防状态 | 已布防

  • 撤防状态 | 已撤防 | | detail | DetailObject | N | 布防/撤防详情 |

DetailObject：

属性

类型

可选

说明

sid

int

否

安防模式id

name

string

否

安防名称

示例

6. TTS（文本转语音）引擎功能

6.1 说明

关键角色

  • TTS 服务提供方：负责在网关上注册 TTS 引擎并提供 TTS 服务的引擎服务提供方

  • 网关服务器：iHost

  • 网关开放 API 客户端

6.1.1 注册 TTS 引擎服务

  1. 【TTS 服务提供方】调用接口在网关上注册 TTS 引擎。

  2. 【网关服务器】注册成功后，网关将存储 TTS 引擎的基本信息（包括服务地址 server_address，后续网关与 TTS 服务提供方之间的通信将通过该 server_address 地址进行），并在网关内部分配 TTS 引擎服务 ID。

image.png

6.1.2 获取合成音频列表

  1. 【网关开放 API 客户端】调用接口获取已注册的 TTS 引擎服务列表。可获得当前已注册 TTS 引擎的列表（包括网关分配的 TTS 引擎 ID）。

  2. 【网关开放 API 客户端】调用接口获取指定 TTS 引擎的音频列表。网关会向指定的 TTS 服务提供方下发同步的音频列表指令并返回结果。

image.png

6.1.3 指定语音引擎进行语音合成

  1. 【网关开放 API 客户端】调用接口获取已注册的 TTS 引擎服务列表。可获得当前已注册 TTS 引擎的列表（包括网关分配的 TTS 引擎 ID）。

  2. 【网关开放 API 客户端】调用接口获取指定 TTS 引擎的音频列表。网关会向指定的 TTS 服务提供方下发同步的音频列表指令并返回结果。

image.png

6.1.4 合成音频并播放 TTS 语音。

  1. 【网关开放 API 客户端】调用接口获取已注册的 TTS 引擎服务列表。可获得当前已注册 TTS 引擎的列表（包括网关分配的 TTS 引擎 ID）。

  2. 【网关开放 API 客户端】调用接口获取指定 TTS 引擎的音频列表。网关会向指定的 TTS 服务提供方下发同步的音频列表指令并返回结果。（包括 TTS 音频文件地址）

  3. 【网关开放 API 客户端】从上一步返回的结果中记录 TTS 音频文件地址，调用播放音频文件接口，通过网关进行播放。

6.2 TTS 引擎模块

6.2.1 网关开放能力

a. 获取已注册的 TTS 引擎服务列表

:::提示

  • URL：/open-api/V2/rest/tts/engines

  • 方法：GET

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：无 正确数据响应：

属性

类型

可选

说明

engines

EngineObject []

否

已注册 TTS 引擎列表

EngineObject 结构

属性

类型

可选

说明

id

string

否

网关分配的引擎 ID

name

string

否

TS 引擎服务名称

:::提示 条件：请求参数合法，且通过用户身份校验。**状态码：**200 OK 响应示例：： :::

b. 获取指定 TTS 引擎的音频列表

:::提示

  • URL：/open-api/V2/rest/tts/engine/{id}/audio-list

  • 方法：GET

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：无 正确数据响应：

属性

类型

可选

说明

audio_list

AudioObject []

否

音频列表

AudioObject 结构

属性

类型

可选

说明

url

string

否

音频文件 URL，例如：

https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3

label

string

是

音频文件标签

:::提示 条件：请求参数合法，且通过用户身份校验。**状态码：**200 OK **错误代码：**

  • 190000 引擎运行异常

响应示例：： :::

c. 使用指定 TTS 引擎执行语音合成

:::提示

  • URL：/open-api/V2/rest/tts/engine/{id}/synthesize

  • 方法：POST

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：

属性

类型

可选

说明

text

string

否

用于合成音频的文本

label

string

是

音频文件标签

language

string

是

透明字段。合成语音请求的可选语言代码。具体支持的语言代码列表由 TTS 语音引擎服务提供方提供。注意 TTS 引擎服务需要支持默认语言进行语音合成，即当未传入 language 时将使用引擎的默认语言进行合成。

options

object

是

透明字段。用于向 TTS 语音引擎服务传递合成所需的配置参数。

正确数据响应：

属性

类型

可选

说明

audio

AudioObject

否

音频列表

AudioObject 结构

属性

类型

可选

说明

url

string

否

音频文件 URL，例如：

https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3

label

string

是

音频文件标签

:::提示 条件：请求参数合法，且通过用户身份校验。**状态码：**200 OK **错误代码：**

  • 190000 引擎运行异常

响应示例：： :::

6.2.2 网关与 TTS 服务之间的通信

a. 注册 TTS 引擎服务

由 TTS 服务提供方向网关发送请求

:::提示

  • URL：/open-api/V2/rest/thirdparty/event

  • 方法：POST

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：

属性

类型

可选

说明

event

EventObject

否

请求事件对象结构信息

EventObject

属性

类型

可选

说明

header

HeaderObject

否

请求头结构信息

payload

PayloadObject

否

请求负载结构信息

HeaderObject

属性

类型

可选

说明

name

string

否

请求名称。可选参数。

  • RegisterTTSEngine | | message_id | string | N | 请求消息 ID，UUID_V4 | | version | string | N | 请求协议版本号。目前固定为 1 |

PayloadObject

属性

类型

可选

说明

service_address

string

否

服务地址。例如，http:///

name

string

否

服务名称

请求示例：

**正确响应参数：**

属性

类型

可选

说明

header

HeaderObject

否

请求头结构信息

payload

PayloadObject

否

请求负载结构信息

HeaderObject

属性

类型

可选

说明

name

string

否

响应头名称。可选参数：

  • 响应（成功响应）

  • ErrorResponse（错误响应） | | message_id | string | N | 响应头消息 ID，UUID_V4。此处为入参请求消息：header.message_id | | version | string | N | 请求协议版本号。目前固定为 1 |

PayloadObject

属性

类型

可选

说明

engine_id

string

否

网关分配的引擎 ID

:::提示 条件：请求参数合法，且通过用户身份校验。**状态码：**200 OK 响应示例：： ::: 正确响应示例：：

**异常响应参数：**

属性

类型

可选

说明

type

string

否

错误类型

  • INVALID_PARAMETERS（参数错误）

  • AUTH_FAILURE（认证失败）

  • INTERNAL_ERROR（服务内部错误） | | description | string | N | 错误描述 |

错误响应示例：：

b. 同步音频列表命令

由网关向 TTS 服务提供方发送命令。

:::提示

  • URL：<service address>

  • 方法：POST

  • Header：

    • Content-Type: application/json ::: 请求参数：

属性

类型

可选

说明

directive

DirectiveObject

否

指令对象结构信息

DirectiveObject

属性

类型

可选

说明

header

HeaderObject

否

请求头结构信息

payload

PayloadObject

否

请求负载结构信息

HeaderObject

属性

类型

可选

说明

name

string

否

请求名称。可选参数：

  • SyncTTSAudioList | | message_id | string | N | 请求消息 ID，UUID_V4 | | version | string | N | 请求协议版本号。目前固定为 1 |

请求示例：

**正确响应参数：**

属性

类型

可选

说明

header

HeaderObject

否

请求头结构信息

payload

PayloadObject

否

请求负载结构信息

HeaderObject

属性

类型

可选

说明

name

string

否

响应头名称。可选参数：

  • 响应（成功响应）

  • ErrorResponse（错误响应） | | message_id | string | N | 响应头消息 ID，UUID_V4。此处为入参请求消息：header.message_id | | version | string | N | 请求协议版本号。目前固定为 1 |

PayloadObject：

属性

类型

可选

说明

audio_list

AudioObject []

否

TTS 音频列表

AudioObject 结构

属性

类型

可选

说明

url

string

否

音频文件 URL，例如：

https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3

label

string

是

音频文件标签

:::提示 条件：请求参数合法，且通过用户身份校验。**状态码：**200 OK 响应示例：： ::: 正确响应示例：：

**异常响应参数：**

属性

类型

可选

说明

type

string

否

错误类型

  • INVALID_PARAMETERS（参数错误）

  • AUTH_FAILURE（认证失败）

  • INTERNAL_ERROR（服务内部错误） | | description | string | N | 错误描述 |

错误响应示例：：

c. 语音合成命令

由网关向 TTS 服务提供方发送命令。

:::提示

  • URL：<service address>

  • 方法：POST

  • Header：

    • Content-Type: application/json ::: 请求参数：

属性

类型

可选

说明

directive

DirectiveObject

否

指令对象结构信息

DirectiveObject

属性

类型

可选

说明

header

HeaderObject

否

请求头结构信息

payload

PayloadObject

否

请求负载结构信息

HeaderObject

属性

类型

可选

说明

name

string

否

请求名称。可选参数：

  • SynthesizeSpeech | | message_id | string | N | 请求消息 ID：UUID_V4 | | version | string | N | 请求协议版本号。目前固定为 1 |

PayloadObject

属性

类型

可选

说明

text

string

否

用于合成音频的文本

label

string

是

音频文件标签

language

string

是

透明字段。合成语音请求的可选语言代码。具体支持的语言代码列表由 TTS 语音引擎服务提供方提供。注意 TTS 引擎服务需要支持默认语言进行语音合成，即当未传入 language 时将使用引擎的默认语言进行合成。

options

object

是

透明字段。用于向 TTS 语音引擎服务传递合成所需的配置参数。

请求示例：

**正确响应参数：**

属性

类型

可选

说明

header

HeaderObject

否

请求头结构信息

payload

PayloadObject

否

请求负载结构信息

HeaderObject

属性

类型

可选

说明

name

string

否

响应头名称。可选参数：

  • 响应（成功响应）

  • ErrorResponse（错误响应） | | message_id | string | N | 响应头消息 ID，UUID_V4。此处为入参请求消息：header.message_id | | version | string | N | 请求协议版本号。目前固定为 1 |

PayloadObject

属性

类型

可选

说明

audio

AudioObject

否

TTS 音频

AudioObject 结构

属性

类型

可选

说明

url

string

否

音频文件 URL，例如：

https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3

label

string

是

音频文件标签

:::提示 条件：请求参数合法，且通过用户身份校验。**状态码：**200 OK 响应示例：： ::: 正确响应示例：：

**异常响应参数：**

属性

类型

可选

说明

type

string

否

错误类型

  • INVALID_PARAMETERS（参数错误）

  • AUTH_FAILURE（认证失败）

  • INTERNAL_ERROR（服务内部错误） | | description | string | N | 错误描述 |

错误响应示例：：

7. 多媒体模块

7.1 播放音频文件

:::提示

  • URL：/open-api/V2/rest/media/audio-player

  • 方法：POST

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：

属性

类型

可选

说明

audio_url

string

否

音频 URL 地址

正确数据响应： :::提示 条件：请求参数合法，且通过用户身份校验。**状态码：**200 OK 响应示例：： :::

8. 自定义 UI 卡片

自定义 UI 卡片允许您在卡片内显示任意想要的内容。该内容可以是网页、图片或任何具有 UI 的服务。您只需提供希望展示内容的 URL。UI 卡片会自动适应其宽高，内容将通过 iFrame 渲染。

8.1 说明

关键角色

  • UI 服务提供方：负责在网关上创建自定义 UI 卡片的提供方。

  • 网关服务器：网关服务器（iHost）。

  • 网关开放 API 客户端：网关的 Open API 客户端。

8.1.1 创建自定义 UI 卡片

  • [UI 服务提供方]：调用 API 在网关上创建自定义 UI 卡片。

  • [网关服务器]：注册成功后，网关将存储 UI 卡片的基本信息（包括尺寸配置和卡片资源 URL）并在网关内部分配一个 UI 卡片 ID。

image.png

8.1.2 获取 UI 卡片列表

  • [UI 服务提供方]：调用 API 获取 UI 卡片列表。

  • [网关服务器]：返回网关上存储的 UI 卡片列表，包括调用者未创建的自定义 UI 卡片。

image.png

8.1.3 修改指定 UI 卡片的配置

  • [UI 服务提供方]：调用 API 修改指定 UI 卡片的配置，例如尺寸配置和资源 URL。

  • [网关服务器]：修改成功后，网关将存储更新后的 UI 卡片信息，包括新的尺寸配置和资源 URL。

image.png

8.1.4 删除自定义 UI 卡片

  1. [UI 服务提供方]：调用 API 删除指定的自定义 UI 卡片。

  2. [网关服务器]：网关将移除与指定 UI 卡片相关的所有信息。

image.png

8.2 自定义 UI 卡片模块

8.2.1 创建自定义 UI 卡片

UI 服务提供方向网关发送请求以创建自定义 UI 卡片。

:::提示

  • URL：/open-api/v2/rest/ui/cards

  • 方法：POST

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：

属性

类型

可选

说明

label

string

是

卡片标签：用于描述卡片。它是卡片的别名。

cast_settings

CastSettingsObject

是

投屏卡片设置：投屏卡片的配置设置。

web_settings

WebSettingsObject

否

网页卡片设置：网页卡片的配置设置。

CastSettingsObject：

属性

类型

可选

说明

dimensions

DimensionObject []

否

尺寸配置：必须至少包含一个配置。

default

string

否

默认规格：默认使用的尺寸规格，可选参数：2x2

WebSettingsObject：

属性

类型

可选

说明

dimensions

DimensionObject []

否

尺寸配置：必须至少包含一个配置。

drawer_component

DrawerObject

是

抽屉组件显示设置。

default

string

否

默认规格：

  • 1x1

  • 2x1 |

DimensionObject：

属性

类型

可选

说明

src

string

否

资源 URL：例如：http://example.html

size

string

否

尺寸规格：

CastSettingsObject 可选参数：

  • 2×2

WebSettingsObject 可选参数：

  • 1x1

  • 2x1 |

DrawerObject：

属性

类型

可选

说明

src

string

否

资源 URL：例如：http://example.html

成功的数据响应：

属性

类型

可选

说明

id

string

否

UI 卡片唯一 ID

:::提示 条件：请求参数合法且通过用户身份验证。**状态码：** 200 OK ::: 请求示例：

响应示例：

8.2.2 获取 UI 卡片列表

:::提示

  • URL：/open-api/v2/rest/ui/cards

  • 方法：GET

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：无 响应参数：

属性

类型

可选

说明

data

CardObject[]

否

UI 卡片列表

CardObjec 对象：

属性

类型

可选

说明

id

string

否

卡片 ID：卡片的唯一标识符。

label

string

是

卡片标签：用于描述卡片。作为卡片的别名或名称。

cast_settings

CastSettingsObject

是

卡片标签：用于描述卡片。它是卡片的别名。

web_settings

WebSettingsObject

否

投屏卡片设置：投屏卡片的配置设置。

app_name

string

是

网页卡片设置：网页卡片的配置设置。

CastSettingsObject：

属性

类型

可选

说明

dimensions

DimensionObject []

否

尺寸配置：必须至少包含一个配置。

default

string

否

默认规格：

可选参数：2x2

used

string

否

当前规格：

可选参数：2x2

WebSettingsObject：

属性

类型

可选

说明

dimensions

DimensionObject []

否

尺寸配置：必须至少包含一个配置。

drawer_component

DrawerObject

是

抽屉组件显示设置。

default

string

否

默认规格：

可选参数：

  • 1x1

  • 2x1 | | used | string | N | 当前规格：可选参数：

  • 1x1

  • 2x1 |

DimensionObject：

属性

类型

可选

说明

src

string

否

资源 URL：例如：http://example.html

size

string

否

尺寸规格：

可选参数：

  • 1x1

  • 2x1

注意：目前，投屏卡片仅支持 2x2 规格。2x2 规格将不会生效。 |

DrawerObject：

属性

类型

可选

说明

src

string

否

资源 URL：例如：http://example.html

响应示例：

8.2.3 修改指定 UI 卡片的配置

经授权的用户可通过此接口修改现有 UI 卡片的配置。自定义卡片服务提供方只能修改其创建的 UI 卡片。

:::提示

  • URL：/open-api/v2/rest/ui/cards/{id}

  • 方法：PUT

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：

属性

类型

可选

说明

label

string

是

用于描述卡片。它是卡片的别名。

cast_settings

CastSettingsObject

是

投屏卡片设置

web_settings

WebSettingsObject

是

网页卡片设置

CastSettingsObject：

属性

类型

可选

说明

used

string

Y，两者之一 used 或 src 必须提供，但至少需要提供这些参数中的一个。

当前规格：

可选参数：

  • 2x2

| | src | string | Y，两者之一 used 或 src 必须提供，但至少需要提供这些参数中的一个。 | 资源 URL： http://example.html |

WebSettingsObject：

属性

类型

可选

说明

used

string

Y，两者之一 used 或 src 必须提供，但至少需要提供这些参数中的一个。

当前规格：

可选参数：

  • 1x1

  • 2x1 | | src | string | Y，两者之一 used 或 src 必须提供，但至少需要提供这些参数中的一个。 | 资源 URL： http://example.html |

数据响应成功： :::tips 条件：请求参数合法，且通过用户身份校验。被修改的 UI 卡片必须由调用接口的自定义 UI 卡片服务提供方创建。**状态码：** 200 OK 错误代码：

  • 406：无权限访问该资源 ::: **响应示例：**

**请求示例：**

8.2.4 删除自定义 UI 卡片

经授权的用户可使用此接口删除现有的 UI 卡片。自定义卡片服务提供方只能删除由其创建的 UI 卡片。

:::提示

  • URL：/open-api/v2/rest/ui/cards/{id}

  • 方法：DELETE

  • Header：

    • Content-Type: application/json

    • Authorization: Bearer ::: 请求参数：无 成功数据响应： :::提示 条件：请求参数合法，且通过用户身份校验。被修改的 UI 卡片必须由调用接口的自定义 UI 卡片服务提供方创建。**状态码：** 200 OK 错误代码：

  • 406：无权限访问该资源。 ::: **响应示例：**

上一页更新日志下一页语言

最后更新于