智兰开放平台

快速开始

智兰开放平台把您的设备无缝接入智能家居生态——AI 智能体、智能家居平台、行业云都能轻松对接。下面两种接入方式任选其一，凭证同源、能力等价。

1

微信小程序
「我的 → OpenAPI」
一键获取接入凭证

2

复制凭证内容
发送给 AI Agent
（或按下方方式接入）

3

读取设备温湿度光照数据
（开通控制权限后）
控制灯/风扇/加湿

Base URL:  
MCP 端点:  
认证方式:  Authorization: Bearer zk_xxx（两种接入方式共用同一凭证）
频率限制:  60 次/分钟/Token
权限范围:  默认只读；开通控制权限后可控制设备（灯/风扇/加湿）

Agent 接入模板

将以下内容提供给 AI Agent（如 Claude、GPT），即可自动生成调用技能：

REST 与 MCP 两条通道能力等价：支持 MCP 的客户端优先添加 MCP 端点（工具经 tools/list 动态发现），不支持的环境用 REST 接口直调。

适合：智能家居方向的 AI 智能体（Claude、ChatGPT Connectors 等原生支持 MCP 的客户端）

将下方端点添加为 MCP 服务器，即可用原生工具方式访问设备——工具自动发现、无需手写接口调用：

MCP 端点:   
传输方式:   Streamable HTTP
认证 Header:  Authorization: Bearer zk_xxx（与 REST 接口相同的 Token）

工具	说明	只读凭证	可控凭证
`list_devices`	设备列表 + 最新传感器数据	✓	✓
`get_device`	设备详情	✓	✓
`get_device_data`	历史遥测数据	✓	✓
`get_device_trend`	按天聚合趋势	✓	✓
`control_device`	设备控制（白名单属性）	—	✓

工具列表由客户端经 tools/list 动态发现，按凭证权限（scope）而定，只读凭证不可见也不可调用 control_device。
接入要求客户端支持自定义请求 Header（Authorization）；仅支持 OAuth 认证、无法配置该 Header 的 MCP 客户端暂不适用此方式，请改用下方 REST 接口。
凭证在小程序「我的 → OpenAPI」页获取；若需控制设备，请在选中凭证卡内打开「允许控制设备」开关（开启需二次确认，关闭立即生效）。

Machine-Readable Spec（Agent 可直接解析，含完整参数与错误定义）： /openapi-module.json

适合：AI 智能体 + 传统智能家居平台 / 行业云平台集成（标准 OpenAPI 3.0 规范）

接口列表

GET /openapi/me

查询当前凭证信息（scope 探测）——返回 name / token_prefix / scope，无需发真实控制指令即可得知凭证权限

GET /openapi/devices

获取用户所有设备及最新传感器数据

GET /openapi/devices/{device_name}

获取单台设备详情（设备信息 + 执行器状态 + 最新数据）

参数	位置	说明
`device_name`	path	设备序列号

GET /openapi/devices/{device_name}/data

获取历史遥测数据（列定义从物模型动态解析，返回 columns + records）

参数	位置	说明
`device_name`	path	设备序列号
`limit`	query	返回条数，默认 20，最大 100

GET /openapi/devices/{device_name}/data/trend

获取按天聚合的趋势数据（温度均值/最高/最低、湿度、光照、土壤湿度）

参数	位置	说明
`device_name`	path	设备序列号
`days`	query	查询天数，默认 7，最大 365

POST /openapi/devices/{device_name}/properties

设备控制：设置执行器属性（需凭证已开通控制权限，scope=read_write）。
白名单属性：led_on / led_brightness / fan_on / fan_speed / mist_on；逐属性返回 status：sent（已下发在线设备）/ pending（设备离线，已缓存待上线应用）/ rejected（白名单外或校验失败，不影响其余合法属性）

参数	位置	说明
`device_name`	path	设备序列号
body	body	属性键值对（可多项），如 `{"led_brightness": 80}`

OpenAPI 错误码

code	说明
0	成功
400	参数错误
401	Token 无效或已过期
403	无权访问该设备
404	设备不存在
429	请求过于频繁（超过 60 次/分钟）
500	服务器内部错误

设备控制（POST .../properties）端点直接返回上述对应 HTTP 状态码（400/403/404），响应体结构相同。

接入方式一：MCP（Model Context Protocol）

接入方式二：OpenAPI（REST）