开发者与 API 指南
1. 开始使用
1.1 准备
步骤1. 请确保网关已通电并正常工作。
步骤2. 确保网关与 PC 连接到同一局域网。然后在浏览器中输入 CUBE 的 URL。
注意：如果您有多个网关，可以通过以下两种方式获取相应的 IP 地址以访问指定网关。
登录到您的无线路由器并在 DHCP 中检查网关的 IP 地址。
CUBE 支持通过 mDNS 本地发现。
1.2 开始使用
调用 [Access Token] 接口，收到错误响应，提示点击 <完成>。注意，按下后，接口访问有效时间不超过 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"
}点击 <完成> 并再次调用 [Access Token] 接口。响应成功，获取到 token。
验证 token。调用 [Get Device List] 接口。响应成功，获取到设备列表。
获取 CUBE 访问令牌的方法：调用 [Access Token] 接口后，CUBE Web 控制台页面会弹出全局提示框，提示用户确认获取接口调用凭据。
注意：如果打开多个 CUBE Web 控制台页面，确认弹框会同时出现在多个页面上，在任一页面点击确认后，其他页面的弹框将被关闭。
2. 核心概念
2.1 开发接口地址
网关 Web API 接口有两种访问方式（基于 IP 或域名），通常根路径为 /open-api/V2/rest/< specific function module >
// IP 访问 http:///open-api/V2/rest/bridge
// 域名访问 http:///open-api/V2/rest/bridge
2.2 设备显示类别与能力
**设备显示类别（DisplayCategory）。**设备显示类别用于识别设备的具体类别，例如开关、插座、灯等。 此信息将决定设备在网关中的 UI 显示效果.
**设备能力（Capability）。**设备能力用于描述设备的具体子功能。例如电源控制、亮度控制、色温控制等。 单个设备可以支持一个或多个能力.
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"
位说明：
位 0： 允许查看该配置项
位 1： 允许修改该配置项 | | 类型 | string | N | 描述配置项值的数据类型。 可选值：
"enum""numeric""object""boolean""string"
类型相关指南：
当
**type = enum**:当
value字段（描述配置项的值）在permission允许修改（"10"或"11").当
default（描述配置项的默认值）和values（描述配置项的可选值）字段为可选。
当
**type = numeric**:当
value字段在permission允许修改（"10"或"11").以下字段为可选：
min（描述配置项的最小值）max（描述配置项的最大值）step（描述配置项的步长值）precision（描述精度）unit（描述配置项的单位）default（描述默认值）
当
**type = object**:当
value字段在permission允许修改（"10"或"11").当
default字段为可选。
当
**type = boolean**:当
value字段在permission允许修改（"10"或"11").当
default字段为可选。
当
**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） | | 支持的 deep | - bootComplete（系统启动完成）
networkConnected（网络已连接）
networkDisconnected（网络已断开）
systemShutdown（系统关闭） -deviceDiscovered（发现设备）
system Armed（系统布防启用）
system Disarmed（系统布防禁用）
factoryReset（恢复出厂设置） |
3.1 网关功能
a. 访问令牌
允许用户获取访问令牌。
注意：设备重置后令牌将被清除。
注意：获取令牌后，需要再次按按钮才能成功获取新的令牌。
:::提示
URL：
/open-api/V2/rest/bridge/access_token方法：
GET头部：
Content-Type: application/json ::: 请求参数：
属性
类型
是否可选
描述
app_name
string
Y
应用名称描述。
成功的数据响应：
属性
类型
是否可选
描述
token
string
否
接口访问令牌。有效期较长，请保存
app_name
string
Y
应用名称描述。
:::提示 条件：用户触发 < command key > 并在有效时间内访问此接口。**状态代码：**200 OK ::: 响应示例:
失败的数据响应：空对象 :::提示 条件：用户未触发 < command key >，或有效时间已过期。**状态代码：** 200 OK ::: 响应示例:
b. 获取网关状态
允许授权用户通过此接口获取网关状态 :::提示
URL：
/open-api/V2/rest/bridge/runtime方法：
GET头部：
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
Y
SD 卡使用率（百分比）：
范围：[0-100] 精确到一位小数
*注意：如果未插入 SD 卡或未格式化，则该值为空。
:::提示 条件：请求参数合法且用户身份验证通过。**状态代码：**200 OK ::: 响应示例:
c. 设置网关
允许授权用户通过此接口设置网关 :::提示
URL：
/open-api/V2/rest/bridge/config方法：
PUT头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数：
属性
类型
是否可选
描述
volume
int
Y
系统音量。[0-100]
成功的数据响应：空对象 {} :::提示 条件：请求参数合法且用户身份验证通过。**状态代码：**200 OK ::: 响应示例:
d. 获取网关信息
允许授权用户通过此接口获取网关信息 :::提示
URL：
/open-api/V2/rest/bridge方法：
GET头部：
Content-Type: application/json ::: 请求参数：
属性
类型
是否可选
描述
ip
string
否
IP 地址
mac
string
否
MAC 地址
domain
string
Y
网关服务域名
fw_version
string
否
固件版本
name
string
否
设备名称
成功的数据响应：空对象 {} :::提示 条件：无 **状态代码：**200 OK ::: 响应示例:
e. 网关静音
允许授权用户通过此接口将网关静音。 :::提示
URL：
/open-api/v2/rest/bridge/mute方法：
PUT头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::提示 条件：请求参数合法且用户身份验证通过。**状态代码：**200 OK ::: 响应示例:
f. 取消网关静音
允许授权用户通过此接口取消网关静音。 :::提示
URL：
/open-api/v2/rest/bridge/unmute方法：
PUT头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::提示 条件：请求参数合法且用户身份验证通过。**状态代码：**200 OK ::: 响应示例:
g. 取消网关警报
允许授权用户通过此接口禁用网关上的警报声音状态。 :::提示
URL：
/open-api/v2/rest/bridge/cancel_alarm方法：
PUT头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::提示 条件：请求参数合法且用户身份验证通过。**状态代码：**200 OK ::: 响应示例:
3.2 硬件功能
a. 重启网关
允许被授权用户通过此接口重启网关 :::提示
URL：
/open-api/V2/rest/hardware/reboot方法：
POST头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::提示 条件：请求参数合法且用户身份验证通过。**状态代码：**200 OK :::
b. 扬声器控制
允许被授权用户通过此接口控制扬声器 :::提示
URL：
/open-api/V2/rest/hardware/speaker方法：
POST头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数：
属性
类型
是否可选
描述
type
string
否
可选参数：1.play_sound（播放声音） 2.play_beep（播放蜂鸣）
sound
SoundObject
Y（若 type 为 play_sound 则为 N。）
声音对象。
beep
BeepObject
Y（若 type 为 play_beep 则为 N。）
蜂鸣对象
SoundObject
属性
类型
是否可选
描述
name
string
否
声音名称。支持的取值可在【资源列表 - 支持的声音】中查看
volume
int
否
声音音量。[0-100]
countdown
int
否
扬声器播放声音的时长，时间到后会自动停止播放。单位：秒。[0,1799]
BeepObject
属性
类型
是否可选
描述
name
string
否
deep 名称。支持的取值可在【资源列表 - 支持的 deep】中查看
volume
int
否
deep 音量。[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)
能力声明示例：
属性（状态）：
协议（查询状态与控制指令）：
门磁开关检测（接触）
能力声明示例：
属性（状态）：
协议（查询状态与控制指令）：
运动检测（motion）
能力声明示例：
属性（状态）：
协议（查询状态与控制指令）：
漏水检测（water-leak）
能力声明示例：
属性（状态）：
协议（查询状态与控制指令）：
窗户检测开关（window-detection）
能力声明示例：
属性（状态）：
协议（查询状态与控制指令）：
儿童锁开关（child-lock）
能力声明示例：
属性（状态）：
协议（查询状态与控制指令）：
防直吹开关（anti-direct-blow）
能力声明示例：
属性（状态）：
协议（查询状态与控制指令）：
水平摆风开关（horizontal-swing）
能力声明示例：
属性（状态）：
协议（查询状态与控制指令）：
垂直摆风开关（vertical-swing）
能力声明示例：
属性（状态）：
协议（查询状态与控制指令）：
节能模式开关（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-index）
能力声明示例：
属性（状态）：
协议（查询状态与控制指令）：
天然气检测（gas）
能力声明示例：
属性（状态）：
协议（查询状态与控制指令）：
灌溉工作状态（irrigation/work-status）
能力声明示例：
属性（状态）：
协议（查询状态与控制指令）：
工作状态上报：
工作状态查询：
工作状态查询结果：
灌溉工作模式（irrigation/work-mode）
能力声明示例：
属性（状态）：
协议（查询状态与控制指令）：
自动灌溉控制器（irrigation/auto-controller）
能力声明示例：
属性（状态）：
单次或循环定时：
单次或循环定量：
协议（查询状态与控制指令）：
单次或循环定时：
单次或循环定量：
支持的预设模式
风扇档位（fanLevel）
"low"
"medium"
"high"
恒温器模式（thermostatMode）
"auto"
"manual"
空调模式 >= 1.11.0（airConditionerMode）
"cool"
"heat"
"auto"
"fan"
"dry"
风扇模式 >= 1.11.0（fanMode）
"normal"
"sleep"
"child"
水平角度 >= 1.11.0（horizontalAngle）
"30"
"60"
"90"
"120"
"180"
"360"
垂直角度 >= 1.11.0（verticalAngle）
"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
头部：
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
头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数：
属性
类型
是否可选
描述
name
string
否
子设备名称
display_category
string
否
设备类型。仅支持摄像头。
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
Y
摄像流配置。
SettingsObject
属性
类型
是否可选
描述
streamSetting
StreamSettingObject
否
流服务配置
StreamSettingObject
属性
类型
是否可选
描述
type
string
否
流服务配置
permission
string
否
能力权限。仅支持 "11"（可修改）。
value
StreamSettingValueObject
否
具体配置值
StreamSettingValueObject
属性
类型
是否可选
描述
stream_url
string
否
流 URL 格式
格式：<schema>://<hostname>:<port>/<username>:<password>@<service_path>
方案选项：
rtsp （实时流传输协议）
http （超文本传输协议）— 适用于 ESP32-CAM 设备
*注意：有些摄像机可能不需要用户名或密码。在此情况下，可以从 URL 中省略 <username> 和 <password> 字段。
成功的数据响应：
属性
类型
是否可选
描述
serial_number
string
否
设备唯一序列号
:::提示 条件：请求参数合法且用户身份验证通过。**状态代码：**200 OK ::: 响应示例:
失败数据响应：空对象 :::tips 条件：
摄像机流地址访问错误（格式错误、授权失败、网络异常等）
设备已存在
若单个设备添加失败，则返回所有设备添加失败。
状态码: 200 OK 错误代码： ● 110009 摄像机 IP 地址错误 ● 110010 摄像机访问授权错误 ● 110011 摄像机流地址错误 ● 110012 摄像机视频编码不支持 ● 110013 设备已存在 ::: 响应示例:
g. 获取子设备列表
允许授权用户通过该接口获取网关子设备列表。 :::tips
URL：/open-api/V2/rest/devices
方法: GET
头部：
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
Y
设备主机名
mac_address
string
Y
设备 MAC 地址
app_name
string
Y
所属应用的名称。如果在获取开放接口证书时填写了 app_name，那么后续通过该证书连接的所有设备都会写入此字段。
display_category
string
否
设备分类
capabilities
CapabilityObject[]
否
设备能力
protocol
string
当连接第三方设备时为 "N"，否则为 "Y"
设备协议：zigbee、onvif、rtsp、esp32-cam
state
object
Y
设备状态对象。有关不同能力的状态示例，请查看【支持的设备能力】
标签
object
Y
JSON 格式的键值，自定义设备信息。用途如下：- 用于存储设备通道- 用于存储温度单位- 存储其他第三方设备的自定义信息
在线
boolean
否
在线状态：True 表示在线；False 表示离线
子网
boolean
Y
是否与网关在同一子网内
CapabilityObject 💡注意：请查看【支持的设备能力】中的支持设备能力示例。
属性
类型
是否可选
描述
capability
string
否
能力名称。详情请参见【支持的设备能力】
permission
string
否
能力权限。可能的值为“read”（可读）、“write”（可写）、“readWrite”（可读可写）。
configuration
object
Y
能力配置信息。目前用于 camera-stream，详见【支持的设备能力】
name
string
Y
toggle 中的 name 字段。用于标识多通道设备的子通道编号。例如，name 为 1 表示通道 1。
:::提示 条件：请求参数合法且用户身份验证通过。**状态代码：**200 OK ::: 响应示例:
h. 更新指定设备信息或状态
允许授权用户通过此接口修改子设备的基本信息并发送控制命令。:::tips
URL：/open-api/V2/rest/devices/{serial_number}
方法：PUT
头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数：
属性
类型
是否可选
描述
name
string
Y
设备名称
标签
object
Y
JSON 格式的键值，自定义设备信息。
state
object
Y
设备状态对象。有关不同能力的状态示例，请查看【支持的设备能力】
configuration
object
Y
能力配置信息，目前仅 camera_stream 能力支持修改。
成功的数据响应：:::tips 条件：请求参数合法，且用户身份验证通过。**状态码：**200 OK 错误代码:
110000：对应 id 的子设备/分组不存在 ::: 响应示例:
i. 删除子设备
允许授权用户通过此接口删除子设备。:::tips
URL：/open-api/V2/rest/devices/{serial_number}
方法：DELETE
头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数：
属性
类型
是否可选
描述
name
string
Y
设备名称。
标签
object
Y
以 JSON 格式的键值对，用于存储设备通道名称及子设备的其他信息。
state
object
Y
改变设备状态；具体协议细节请参阅“支持的设备能力”。
capabilities
CapabilityObject []
Y
能力配置信息；所有支持设置配置的能力均可修改。注意，权限（permission）不可更改。
成功的数据响应：:::tips 条件：请求参数合法，且用户身份验证通过。**状态码：**200 OK 错误代码：
110000：对应 ID 的子设备/分组不存在。
110006：更新设备状态失败。
110019：访问第三方设备服务地址失败。
110024：更新设备配置失败。::: 响应示例:
j. 删除子设备
允许授权用户通过此接口删除子设备。 :::tips
URL：
/open-api/v2/rest/devices/{serial_number}方法：
DELETE头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数：无 成功的数据响应：:::tips 条件：请求参数合法且用户身份验证通过。**状态代码：**200 OK ::: 响应示例:
k. 查询设备状态
允许授权用户通过此接口查询设备状态。 :::tips
URL：
/open-api/v2/rest/devices/:serial_number/query-state/{capability}方法：POST
头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数：
属性
类型
是否可选
描述
query_state
object
否
查询设备状态；具体协议细节请参阅“支持的设备能力”。
成功的数据响应：:::tips 条件：请求参数合法且用户身份验证通过。**状态代码：**200 OK ::: 响应示例:
3.4 安全管理
a. 获取安防列表
允许授权用户通过此接口修改网关设置。:::tips
URL：
/open-api/v2/rest/security方法：
GET头部：
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头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::tips 条件：请求参数合法且用户身份验证通过。**状态代码：**200 OK ::: 响应示例:
c. 禁用指定安防模式
允许授权用户通过此接口禁用指定的安防模式。 :::tips
URL：
/open-api/v2/rest/security/{security_id}/disable方法：
PUT头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::tips 条件：请求参数合法且用户身份验证通过。**状态代码：**200 OK ::: 响应示例:
d. 一键启用安防设置
允许授权用户通过此接口启用一键安防设置模式。 :::tips
URL：
/open-api/v2/rest/security/enable方法：
PUT头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::tips 条件：请求参数合法且用户身份验证通过。**状态代码：**200 OK ::: 响应示例:
e. 关闭安防
允许授权用户通过此接口关闭安防。 :::tips
URL：
/open-api/v2/rest/security/disable方法：
PUT头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::tips 条件：请求参数合法且用户身份验证通过。**状态代码：**200 OK ::: 响应示例:
4. 第三方设备接入
4.1 接入说明
设备接入
第三方网关接入
接入步骤
确定设备在网关中的分类。详情请查看【支持的设备类型】。
确定设备可接入的能力。详情请查看【支持的设备能力】。
调用【Discovery Request】接口将设备添加到网关。
注意：您需要提供用于接收网关下发指令的服务地址，用于接收网关下发的设备控制指令.
如果第三方设备状态发生变化，您需要调用【设备状态变更上报（Device States Change Report）】接口将最新状态发送回网关。
添加后，第三方设备将出现在设备列表中，拥有大部分与网关（其他非第三方设备）相同的功能。设备相关的常用开放接口可正常使用。
选择合适的设备类别。分类会影响设备接入网关后 UI 的最终展示效果。
选择正确的设备能力。能力列表将决定设备状态协议的内容。
程序流程
a. 设备接入
b. 第三方网关接入
4.2 接入示例
开关、插座
同步第三方设备
上报设备状态
上报离线/在线
接收关于网关控制设备的指令
查询设备
4.3 Web API
第三方请求网关接口
请求格式
允许授权用户通过此接口向网关发送事件请求。:::tips
URL：/open-api/V2/rest/thirdparty/event
方法：POST
头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数：
属性
类型
是否可选
描述
event
EventObject
否
请求事件对象的结构信息
EventObject
属性
类型
是否可选
描述
header
HeaderObject
否
请求头的结构信息
endpoint
EndpointObject
Y
请求端点的结构信息 注意：同步新设备列表时此字段为空。
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
否
第三方设备唯一序列号
标签
object
Y
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
否
设备型号
标签
object
Y
JSON 格式的键值，自定义设备信息：用于存储设备通道用于存储温度单位其他第三方自定义数据
firmware_version
string
否
固件版本
请求示例：
响应参数： 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 的 设置 键（key）内的 CapabilityObject，且仅当 permission 的 设置 键为 11 或 01时允许更新。关于 设置 在 CapabilityObject中的具体结构定义，请参阅第 2.3 节 设备显示分类与设备能力 的详细描述。 | | tags
| object
| Y
| JSON 格式的键值，自定义设备信息。
可用于存储设备通道
可用于存储温度单位
其他第三方自定义数据 |
请求示例：
响应参数： PayloadObject：空对象 成功响应示例：
网关通过设备服务地址向该接口下发指令
注意：
第三方需在 3 秒内响应网关的请求。否则，网关将判定命令处理超时。
如果第三方服务离线，网关会将设备设置为离线状态，第三方服务需在恢复在线前通过上报设备状态（DeviceStatesChangeReport）或在线状态（DeviceOnlineChangeReport）来使设备返回在线状态。
请求格式
网关通过设备服务地址接口向第三方下发指令。:::tips
URL：
方法：POST
头部：
Content-Type: application/json ::: 请求参数：
属性
类型
是否可选
描述
directive
DirectiveObject
否
指令对象的结构信息
DirectiveObject
属性
类型
是否可选
描述
header
HeaderObject
否
请求头的结构信息
endpoint
EndpointObject
否
请求端点的结构信息
payload
PayloadObject
否
请求负载的结构信息
HeaderObject
属性
类型
是否可选
描述
name
string
否
请求名称。可选参数：UpdateDeviceStates：更新设备状态
message_id
string
否
请求消息 ID，UUID_V4
version
string
否
请求协议版本号。目前固定为 1。
EndpointObject
属性
类型
是否可选
描述
serial_number
string
否
设备唯一序列号
third_serial_number
string
否
第三方设备唯一序列号
标签
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. 服务端事件（SSE）
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
Y
第三方设备的唯一序列号。对于通过开放接口接入的设备，此字段为必填。
示例：
c. 更新设备信息事件
:::tips 模块名称：device 版本：v2 消息类型：updateDeviceInfo event.data 参数： :::
endpoint
EndpointObject
否
设备信息
payload
DeviceChangeObject
否
设备变更数据
EndpointObject：
serial_number
string
否
设备唯一序列号
third_serial_number
string
Y
第三方设备的唯一序列号。对于通过开放接口接入的设备，此字段为必填。
DeviceChangeObject
name
string
否
设备名称
capabilities
CapabilityObject []
Y
设备能力列表。
标签
object
Y
标签object | 可为空 | 用于自定义设备信息的 JSON 格式键值对。
可用于存储设备通道。
可用于存储温度单位。
用于其他第三方自定义数据。 |
示例：
d. 删除设备事件
:::tips 模块名称：device 版本：v2 消息类型：deleteDevice event.data 参数： :::
endpoint
EndpointObject
否
设备信息
EndpointObject：
serial_number
string
否
设备唯一序列号
third_serial_number
string
Y
第三方设备的唯一序列号。对于通过开放接口接入的设备，此字段为必填。
示例：
e. 更新设备在线事件
:::tips 模块名称：device 版本：v2 消息类型：updateDeviceOnline event.data 参数： :::
endpoint
EndpointObject
否
设备信息
payload
DeviceChangeObject
否
设备变更数据
EndpointObject：
serial_number
string
否
设备唯一序列号
third_serial_number
string
Y
第三方设备的唯一序列号。对于通过开放接口接入的设备，此字段为必填。
DeviceChangeObject
在线
boolean
否
设备在线状态
示例：
5.4 网关模块
a. 安防状态更新事件
:::tips 模块名称：device 版本：v2 消息类型：updateDeviceOnline event.data 参数： :::
属性
类型
是否可选
描述
payload
SecurityStateObject
否
设备信息
SecurityStateObject
属性
类型
是否可选
描述
alarm_state
string
否
arming| 已布防disarming| 已撤防 |
示例：
5.5 安防模块
a. 布防状态更新事件
:::tips 模块名称：device 版本：v2 消息类型：updateDeviceOnline event.data 参数： :::
属性
类型
是否可选
描述
payload
ArmStateObject
否
布防与撤防信息
ArmStateObject：
属性
类型
是否可选
描述
arm_state
string
否
arming| 已布防disarming| 已撤防 | | detail | DetailObject | N | 布防/撤防详情 |
DetailObject：
属性
类型
是否可选
描述
sid
int
否
安防模式 id
name
string
否
安防名称
示例
6. TTS (文本转语音) 引擎功能
6.1 说明
关键角色
TTS 服务提供商：TTS 服务引擎提供商负责在网关上注册 TTS 引擎并提供 TTS 服务
网关服务器：iHost
网关开放 API 客户端
6.1.1 注册 TTS 引擎服务
【TTS 服务提供商】调用接口在网关上注册 TTS 引擎。
【网关服务器】注册成功后，网关将存储 TTS 引擎的基本信息（包括服务地址 server_address，后续网关与 TTS 服务提供商之间的通信将通过该 server_address 地址进行），并在网关内部分配 TTS 引擎服务 ID。
6.1.2 获取合成音频列表
【网关开放 API 客户端】调用接口获取已注册 TTS 引擎服务的列表。可以获取当前已注册的 TTS 引擎列表（包括网关分配的 TTS 引擎 ID）。
【网关开放 API 客户端】调用接口获取指定 TTS 引擎的音频列表。网关将向指定的 TTS 服务提供商下发同步的音频列表指令并返回结果。
6.1.3 指定语音引擎进行语音合成
【网关开放 API 客户端】调用接口获取已注册 TTS 引擎服务的列表。可以获取当前已注册的 TTS 引擎列表（包括网关分配的 TTS 引擎 ID）。
【网关开放 API 客户端】调用接口获取指定 TTS 引擎的音频列表。网关将向指定的 TTS 服务提供商下发同步的音频列表指令并返回结果。
6.1.4 合成音频并播放 TTS 语音。
【网关开放 API 客户端】调用接口获取已注册 TTS 引擎服务的列表。可以获取当前已注册的 TTS 引擎列表（包括网关分配的 TTS 引擎 ID）。
【网关开放 API 客户端】调用接口获取指定 TTS 引擎的音频列表。网关将向指定的 TTS 服务提供商下发同步的音频列表指令并返回结果。（包括 TTS 音频文件地址）
【网关开放 API 客户端】从上一步返回的结果中记录 TTS 音频文件地址，调用播放音频文件接口，并通过网关进行播放。
6.2 TTS 引擎模块
6.2.1 网关开放能力
a. 获取已注册 TTS 引擎服务列表
:::提示
URL：
/open-api/V2/rest/tts/engines方法：
GET头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数: 无 正确数据响应:
属性
类型
是否可选
描述
engines
EngineObject []
否
已注册 TTS 引擎列表
EngineObject 结构
属性
类型
是否可选
描述
id
string
否
网关分配的引擎 ID
name
string
否
TTS 引擎服务名称
::: 提示 条件：请求参数合法，且通过用户身份验证。**状态码：**200 OK 响应示例：： :::
b. 获取指定 TTS 引擎的音频列表
:::提示
URL：
/open-api/V2/rest/tts/engine/{id}/audio-list方法：
GET头部：
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
Y
音频文件标签
::: 提示 条件：请求参数合法，且通过用户身份验证。**状态码：**200 OK **错误码：**
190000 引擎运行异常
响应示例：： :::
c. 使用指定 TTS 引擎进行语音合成
:::提示
URL：
/open-api/V2/rest/tts/engine/{id}/synthesize方法：
POST头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数:
属性
类型
是否可选
描述
text
string
否
用于合成音频的文本
label
string
Y
音频文件标签
language
string
Y
透明字段。合成语音请求的可选语言代码。具体支持的语言代码列表由 TTS 语音引擎服务提供商提供。注意 TTS 引擎服务需要支持默认语言进行语音合成，这意味着如果未传入 language，则使用引擎的默认语言进行合成。
options
object
Y
透明字段。用于向 TTS 语音引擎服务传递合成所需的配置参数。
正确数据响应:
属性
类型
是否可选
描述
audio
AudioObject
否
音频列表
AudioObject 结构
属性
类型
是否可选
描述
url
string
否
音频文件 URL，例如：
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
label
string
Y
音频文件标签
::: 提示 条件：请求参数合法，且通过用户身份验证。**状态码：**200 OK **错误码：**
190000 引擎运行异常
响应示例：： :::
6.2.2 网关与 TTS 服务之间的通信
a. 注册 TTS 引擎服务
由 TTS 服务提供商向网关发送请求
:::提示
URL：
/open-api/V2/rest/thirdparty/event方法：
POST头部：
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头部：
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
Y
音频文件标签
::: 提示 条件：请求参数合法，且通过用户身份验证。**状态码：**200 OK 响应示例：： ::: 正确响应示例：：
**异常响应参数：**
属性
类型
是否可选
描述
type
string
否
错误类型
INVALID_PARAMETERS（参数错误）
AUTH_FAILURE（认证失败）
INTERNAL_ERROR（服务内部错误） | | description | string | N | 错误描述 |
错误响应示例：：
c. 语音合成指令
由网关向 TTS 服务提供商发送指令。
:::提示
URL：
<service address>方法：
POST头部：
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
Y
音频文件标签
language
string
Y
透明字段。合成语音请求的可选语言代码。具体支持的语言代码列表由 TTS 语音引擎服务提供商提供。注意 TTS 引擎服务需要支持默认语言进行语音合成，这意味着如果未传入 language，则使用引擎的默认语言进行合成。
options
object
Y
透明字段。用于向 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
Y
音频文件标签
::: 提示 条件：请求参数合法，且通过用户身份验证。**状态码：**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头部：
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 客户端：网关的开放 API 客户端。
8.1.1 创建自定义 UI 卡片
[UI 服务提供商]：调用 API 在网关上创建自定义 UI 卡片。
[网关服务器]：注册成功后，网关会存储 UI 卡片的基本信息（包括尺寸配置和卡片资源 URL）并在网关内部分配 UI 卡片 ID。
8.1.2 获取 UI 卡片列表
[UI 服务提供商]：调用 API 获取 UI 卡片列表。
[网关服务器]：返回存储在网关上的 UI 卡片列表，包括调用方未创建的自定义 UI 卡片。
8.1.3 修改指定 UI 卡片的配置
[UI 服务提供商]：调用 API 修改指定 UI 卡片的配置，例如尺寸配置和资源 URL。
[网关服务器]：修改成功后，网关会存储更新后的 UI 卡片信息，包括新的尺寸配置和资源 URL。
8.1.4 删除自定义 UI 卡片
[UI 服务提供商]：调用 API 删除指定的自定义 UI 卡片。
[网关服务器]：网关将移除与指定 UI 卡片相关的所有信息。
8.2 自定义 UI 卡片模块
8.2.1 创建自定义 UI 卡片
UI 服务提供商向网关发送请求以创建自定义 UI 卡片。
:::提示
URL：
/open-api/v2/rest/ui/cards方法：
POST头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数:
属性
类型
是否可选
描述
label
string
Y
卡片标签：用于描述该卡片。它是卡片的别名。
cast_settings
CastSettingsObject
Y
投屏卡片设置：投屏卡片的配置设置。
web_settings
WebSettingsObject
否
网页卡片设置：网页卡片的配置设置。
CastSettingsObject:
属性
类型
是否可选
描述
dimensions
DimensionObject []
否
尺寸配置：必须至少包含一个配置。
default
string
否
默认规格：使用默认尺寸规格，可选参数：2x2
WebSettingsObject:
属性
类型
是否可选
描述
dimensions
DimensionObject []
否
尺寸配置：必须至少包含一个配置。
drawer_component
DrawerObject
Y
抽屉组件显示设置。
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头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数: 无 响应参数:
属性
类型
是否可选
描述
data
CardObject[]
否
UI 卡片列表
CardObjec 对象：
属性
类型
是否可选
描述
id
string
否
卡片 ID：卡片的唯一标识符。
label
string
Y
卡片标签：用于描述该卡片。它作为卡片的别名或名称。
cast_settings
CastSettingsObject
Y
卡片标签：用于描述该卡片。它是卡片的别名。
web_settings
WebSettingsObject
否
投屏卡片设置：投屏卡片的配置设置。
app_name
string
Y
网页卡片设置：网页卡片的配置设置。
CastSettingsObject:
属性
类型
是否可选
描述
dimensions
DimensionObject []
否
尺寸配置：必须至少包含一个配置。
default
string
否
默认规格：
可选参数：2x2
used
string
否
当前规格：
可选参数：2x2
WebSettingsObject:
属性
类型
是否可选
描述
dimensions
DimensionObject []
否
尺寸配置：必须至少包含一个配置。
drawer_component
DrawerObject
Y
抽屉组件显示设置。
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头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数:
属性
类型
是否可选
描述
label
string
Y
用于描述该卡片。它是卡片的别名。
cast_settings
CastSettingsObject
Y
投屏卡片设置
web_settings
WebSettingsObject
Y
网页卡片设置
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头部：
Content-Type: application/json
Authorization: Bearer ::: 请求参数: 无 成功数据响应: ::: 提示 条件：请求参数合法，且通过用户身份验证。被修改的 UI 卡片必须由调用该接口的自定义 UI 卡片服务提供商创建。**状态码：**
200 OK错误代码：
406：无权限访问此资源。 ::: **响应示例：**
最后更新于