Skip to content

API Reference

Jump to bottom
Justin Gu edited this page May 1, 2026 · 1 revision

API Reference

完整的 REST API 文档。所有接口前缀为 /api，启动后也可通过 Swagger UI 查看：http://127.0.0.1:5000/api/docs/

认证方式

API 支持两种认证方式：

方式 适用场景 Header
JWT Bearer API 调用、第三方集成 Authorization: Bearer <access_token>
Session Cookie Web UI 自动携带

大部分接口同时支持两种方式。

统一响应格式

{
  "success": true,
  "data": {},
  "message": "操作成功"
}

错误响应：

{
  "success": false,
  "message": "错误描述"
}

认证 — Session (/api/auth/)

POST /api/auth/register

用户注册。

// Request
{
  "username": "myuser",
  "password": "123456",
  "email": "user@example.com"  // 可选
}

// Response 201
{
  "success": true,
  "data": { "user_id": 1, "username": "myuser" },
  "message": "注册成功"
}
字段 规则
username 2-64 字符，必填
password 6-128 字符，必填
email 合法邮箱格式，可选

POST /api/auth/login

Session 登录，返回用户信息并设置 session cookie。

// Request
{ "username": "myuser", "password": "123456" }

// Response 200
{
  "success": true,
  "data": {
    "user_id": 1,
    "username": "myuser",
    "is_admin": false
  }
}

POST /api/auth/logout

退出登录，清除 session。

GET /api/auth/me

获取当前登录用户信息。需认证。

// Response 200
{
  "success": true,
  "data": {
    "user_id": 1,
    "username": "myuser",
    "email": "user@example.com",
    "display_name": "My User",
    "is_admin": false
  }
}

POST /api/auth/change-password

修改密码。需认证。

// Request
{
  "old_password": "123456",
  "new_password": "654321"
}

认证 — JWT (/api/auth/jwt/)

POST /api/auth/jwt/login

获取 JWT 令牌，适用于 API 调用和第三方集成。

// Request
{ "username": "myuser", "password": "123456" }

// Response 200
{
  "success": true,
  "data": {
    "access_token": "eyJ...",
    "refresh_token": "eyJ...",
    "user_id": 1,
    "username": "myuser"
  }
}

Token 有效期：access_token 24 小时，refresh_token 7 天。

POST /api/auth/jwt/refresh

刷新 access_token。需在 Header 中携带 refresh_token。

Authorization: Bearer <refresh_token>

// Response 200
{
  "success": true,
  "data": { "access_token": "eyJ..." }
}

小米账号绑定 (/api/xiaomi/)

所有接口需认证。

POST /api/xiaomi/qr-init

生成小米账号绑定二维码。

// Response 200
{
  "success": true,
  "data": {
    "qr_image": "<base64 图片>",
    "poll_id": "xxx"
  }
}

若已绑定：返回 "message": "小米账号已绑定且有效"。

GET /api/xiaomi/qr-poll/<poll_id>

轮询扫码状态。

// Response 200
{
  "success": true,
  "data": {
    "status": "pending"   // pending | success | timeout | error
  }
}

GET /api/xiaomi/status

查看小米账号绑定状态。

DELETE /api/xiaomi/unlink

解绑小米账号。

设备管理 (/api/devices/)

所有接口需认证。

GET /api/devices/

获取设备列表。

参数 类型 说明
home_id query, string 按家庭 ID 过滤
refresh query, boolean 强制刷新缓存，默认 false

GET /api/devices/

获取设备详情及规格（属性、动作列表）。

GET /api/devices//props/<prop_name>

读取设备属性值。

// 示例：获取灯的亮度
GET /api/devices/12345/props/brightness

// Response
{
  "success": true,
  "data": { "prop_name": "brightness", "value": 50 }
}

PUT /api/devices//props/<prop_name>

设置设备属性值。

// 示例：设置灯的亮度
// PUT /api/devices/12345/props/brightness
{ "value": 80 }

POST /api/devices//actions/<action_name>

执行设备动作。

// 示例：执行扫地机开始清扫
// POST /api/devices/12345/actions/start-sweep
{ "value": {} }   // 参数可选

GET /api/devices//stream-info

获取摄像头流信息（IP、Token）。

GET /api/devices/go2rtc-config

获取用户所有摄像头的 go2rtc YAML 配置。

家庭管理 (/api/homes/)

所有接口需认证。

GET /api/homes/

获取家庭列表。

参数 类型 说明
refresh query, boolean 强制刷新缓存

GET /api/homes/<home_id>

获取家庭详情（含设备列表）。

场景执行 (/api/scenes/)

所有接口需认证。

GET /api/scenes/

获取场景列表。

参数 类型 说明
home_id query, string 按家庭过滤
refresh query, boolean 强制刷新缓存

POST /api/scenes/<scene_id>/run

执行场景。

// Response
{
  "success": true,
  "data": { "result": "success" }
}

设备分组 (/api/groups/)

所有接口需认证。

GET /api/groups

获取用户的所有分组。

POST /api/groups

创建分组。

// Request
{ "name": "客厅设备", "icon": "sofa" }  // icon 可选

DELETE /api/groups/<group_id>

删除分组。

POST /api/groups/<group_id>/devices/

将设备添加到分组。

DELETE /api/groups/<group_id>/devices/

将设备从分组移除。

POST /api/devices//favorite

切换设备收藏状态。

GET /api/devices//favorite

查询设备是否已收藏。

// Response
{ "success": true, "data": { "did": "12345", "is_favorite": true } }

自动化规则 (/api/automations/)

所有接口需认证。

GET /api/automations

获取用户的所有自动化规则。

POST /api/automations

创建自动化规则。

// Request
{
  "name": "每晚关灯",
  "trigger_type": "cron",
  "trigger_config": { "hour": 23, "minute": 0 },
  "actions": [
    { "did": "12345", "prop_name": "power", "value": "off" }
  ],
  "enabled": true
}

PUT /api/automations/<rule_id>

更新规则。请求体格式同创建。

DELETE /api/automations/<rule_id>

删除规则。

POST /api/automations/<rule_id>/toggle

启用/禁用规则（切换状态）。

能耗统计 (/api/energy/)

所有接口需认证。

POST /api/energy//log

记录能耗数据。

// Request
{
  "prop_name": "power_consumption",
  "value": 12.5,
  "unit": "kWh"   // 可选
}

GET /api/energy//daily

获取日粒度能耗统计。

参数 类型 说明
days query, int 回溯天数，默认 7，最大 90

GET /api/energy//hourly

获取小时粒度能耗统计。

参数 类型 说明
hours query, int 回溯小时数，默认 24，最大 168

GET /api/energy//latest

获取最新能耗记录。

参数 类型 说明
prop_name query, string 按属性名过滤
limit query, int 返回条数，默认 100，最大 1000

GET /api/energy//props

获取设备的能耗相关属性列表。

API Token (/api/tokens/)

管理第三方访问令牌。所有接口需认证。

GET /api/tokens/

列出当前用户的令牌。

// Response
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Home Assistant",
      "permissions": "read_write",
      "last_used_at": "2026-05-01T12:00:00",
      "created_at": "2026-04-01T08:00:00",
      "expires_at": null
    }
  ]
}

POST /api/tokens/

创建令牌。原始 token 仅在创建时返回一次，请妥善保存。

// Request
{
  "name": "My Integration",
  "permissions": "read_write"   // read_only | read_write
}

// Response 201
{
  "success": true,
  "data": {
    "token": "mijia_xxx...",   // 仅此一次！
    "id": 2,
    "name": "My Integration",
    "permissions": "read_write"
  }
}

DELETE /api/tokens/<token_id>

撤销令牌。

错误码参考

设备接口会将米家 API 错误码映射为标准 HTTP 状态码：

HTTP 米家错误码 说明
400 -704220043 属性值错误
400 -704220025 动作参数个数不匹配
400 -704220035 动作参数错误
403 -704010000 未授权（设备可能已删除）
403 -704030013 属性不可读
403 -704030023 属性不可写
404 -704042001 设备不存在
404 -704040003 属性不存在
404 -704040005 动作不存在
409 -704053100 设备当前状态不允许此操作
500 其他 服务器内部错误
503 -704042011 设备离线
504 -704053036 设备操作超时

下一步：CLI Guide — 命令行工具的完整使用说明。

Clone this wiki locally