当前界面的 API 文档可能更新不及时，最新的 API 文档请从以下网址进行查看
https://cloud.zectrix.com/home/api-docs
API 请求需要在 Header 中携带认证信息：
Authorization: Bearer <token>
或者使用 API Key 方式：
X-API-Key: <api_key>
https://cloud.zectrix.com/open/v1/zt_xxxGEThttps://cloud.zectrix.com/open/v1/devices响应示例:
{
"code": 0,
"data": [
{
"deviceId": "AA:BB:CC:DD:EE:FF",
"alias": "我的设备",
"board": "bread-compact-wifi"
}
]
}
curl 示例:
curl "https://cloud.zectrix.com/open/v1/devices" \
-H "X-API-Key: zt_xxx"
GEThttps://cloud.zectrix.com/open/v1/todos参数:
| 参数名 | 类型 | 说明 |
|---|---|---|
| status | integer | 过滤状态：0=待完成, 1=已完成 |
| deviceId | string | 设备ID(MAC地址)，过滤指定设备的待办 |
响应示例:
{
"code": 0,
"data": [
{
"id": 1,
"title": "买牛奶",
"description": "",
"dueDate": "2026-03-20",
"dueTime": "09:00",
"repeatType": "none",
"status": 0,
"priority": 1,
"completed": false,
"deviceId": "AA:BB:CC:DD:EE:FF",
"deviceName": "我的设备",
"createDate": "2026-03-18 10:00:00",
"updateDate": 1742284800
}
]
}
POSThttps://cloud.zectrix.com/open/v1/todos请求体:
{
"title": "买牛奶",
"description": "",
"dueDate": "2026-03-20",
"dueTime": "09:00",
"repeatType": "none",
"priority": 1,
"deviceId": "AA:BB:CC:DD:EE:FF"
}
请求体参数说明:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| title | string | 是 | 待办标题 |
| description | string | 否 | 待办描述 |
| dueDate | string | 否 | 截止日期，格式：YYYY-MM-DD |
| dueTime | string | 否 | 截止时间，格式：HH:mm |
| repeatType | string | 否 | 重复类型，默认 "none" |
| priority | integer | 否 | 优先级 |
| deviceId | string | 否 | 关联设备ID |
响应示例:
{
"code": 0,
"data": {
"id": 1,
"title": "买牛奶",
"status": 0,
"priority": 1,
"deviceId": "AA:BB:CC:DD:EE:FF",
"createDate": "2026-03-18 10:00:00"
}
}
PUThttps://cloud.zectrix.com/open/v1/todos/{id}路径参数:
| 参数名 | 类型 | 说明 |
|---|---|---|
| id | integer | 待办ID |
请求体示例:
{
"title": "买牛奶和面包"
}
请求体可更新字段:
| 参数名 | 类型 | 说明 |
|---|---|---|
| title | string | 待办标题 |
| description | string | 待办描述 |
| dueDate | string | 截止日期 |
| dueTime | string | 截止时间 |
| repeatType | string | 重复类型 |
| priority | integer | 优先级 |
| deviceId | string | 关联设备ID |
响应示例:
{
"code": 0,
"data": {
"id": 1,
"title": "买牛奶和面包",
"status": 0,
"priority": 1
}
}
PUThttps://cloud.zectrix.com/open/v1/todos/{id}/complete路径参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 是 | 待办ID |
响应示例:
{
"code": 0,
"msg": "success"
}
DELETEhttps://cloud.zectrix.com/open/v1/todos/{id}路径参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 是 | 待办ID |
响应示例:
{
"code": 0,
"msg": "success"
}
POSThttps://cloud.zectrix.com/open/v1/devices/{deviceId}/display/image路径参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| deviceId | string | 是 | 设备ID (MAC地址) |
请求参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| images | file | 是 | 图片文件，支持多张(最多5张)，单张不超过2MB |
| dither | boolean | 否 | 是否使用抖动算法(默认true)，关闭则使用硬阈值二值化 |
| pageId | string | 否 | 页面编号(1-5)，指定后会持久化存储 |
响应示例:
{
"code": 0,
"data": {
"totalPages": 1,
"pushedPages": 1,
"pageId": "1"
}
}
POSThttps://cloud.zectrix.com/open/v1/devices/{deviceId}/display/text路径参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| deviceId | string | 是 | 设备ID (MAC地址) |
请求体:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| text | string | 是 | 文本内容，支持换行符 \n |
| fontSize | integer | 否 | 字体大小 |
| pageId | string | 否 | 页面编号(1-5) |
请求体示例:
{
"text": "今日天气：晴\\n温度：25°C",
"fontSize": 20,
"pageId": "1"
}
响应示例:
{
"code": 0,
"data": {
"totalPages": 1,
"pushedPages": 1,
"pageId": "1"
}
}
POSThttps://cloud.zectrix.com/open/v1/devices/{deviceId}/display/structured-text路径参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| deviceId | string | 是 | 设备ID (MAC地址) |
请求体:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| title | string | 是 | 标题 |
| body | string | 是 | 正文内容，支持换行符 \n |
| pageId | string | 否 | 页面编号(1-5) |
请求体示例:
{
"title": "会议提醒",
"body": "15:00 三楼会议室\\n请带笔记本",
"pageId": "1"
}
响应示例:
{
"code": 0,
"data": {
"totalPages": 1,
"pushedPages": 1,
"pageId": "1"
}
}
DELETEhttps://cloud.zectrix.com/open/v1/devices/{deviceId}/display/pages/{pageId}路径参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| deviceId | string | 是 | 设备ID (MAC地址) |
| pageId | string | 否 | 页面编号，不传则删除全部页面 |
响应示例:
{
"code": 0,
"msg": "success"
}
| code | 含义 |
|---|---|
| 0 | 成功 |
| 其他 | 错误（详见具体错误信息） |
文档获取时间: 2026-04-09