API 文档 - Home Voice Box

认证相关

POST /api/login

用户登录，成功后设置认证 Cookie

请求体：

                                    {
  "password": "your_admin_password"
}
                                

响应（成功）：

                                    {
  "success": true,
  "message": "登录成功"
}
                                

状态码：200

POST /api/logout

用户登出，清除认证 Cookie

响应：

                                    {
  "success": true,
  "message": "已退出登录"
}
                                

状态码：200

GET /api/check-auth

检查当前认证状态

响应：

                                    {
  "authenticated": true,
  "message": "已登录"
}
                                

状态码：200（无需认证）

意图映射管理

GET /api/intents

获取所有意图映射列表

⚠️ 需要认证

响应：

                                    [
  {
    "id": 1,
    "intentName": "TurnOnLight",
    "apiName": "turnOnLight",
    "apiLabel": "打开灯光",
    "entityId": "light.kitchen",
    "replyContent": "好的，已为您打开灯光"
  },
  {
    "id": 2,
    "intentName": "TurnOnSwitch",
    "apiName": "turnOnSwitch",
    "apiLabel": "打开开关",
    "entityId": "switch.kitchen",
    "replyContent": "好的，已为您打开开关"
  }
]
                                

状态码：200

POST /api/intents

创建新的意图映射

⚠️ 需要认证

请求体：

                                    {
  "intentName": "TurnOnLight",
  "apiName": "turnOnLight",
  "apiLabel": "打开灯光",
  "entityId": "light.kitchen",
  "replyContent": "好的，已为您打开灯光"
}
                                

响应：

                                    {
  "id": 1,
  "intentName": "TurnOnLight",
  "apiName": "turnOnLight",
  "apiLabel": "打开灯光",
  "entityId": "light.kitchen",
  "replyContent": "好的，已为您打开灯光"
}
                                

状态码：201

PUT /api/intents/:id

更新指定的意图映射

⚠️ 需要认证

请求体：

                                    {
  "intentName": "TurnOnLight",
  "apiName": "turnOnLight",
  "apiLabel": "打开灯光",
  "entityId": "light.kitchen",
  "replyContent": "好的，已为您打开灯光"
}
                                

状态码：200

DELETE /api/intents/:id

删除指定的意图映射

⚠️ 需要认证

响应：

                                    {
  "success": true
}
                                

状态码：200

设备管理

GET /api/ha-entities

获取所有 Home Assistant 设备列表

⚠️ 需要认证

响应：

                                    {
  "entities": [
    {
      "entity_id": "light.kitchen",
      "friendly_name": "厨房灯",
      "state": "on",
      "domain": "light"
    }
  ]
}
                                

状态码：200

GET /api/ha-entities?domain=light

获取指定类型的设备列表

⚠️ 需要认证

查询参数：

domain：设备类型（可选，如：light、fan、switch）

状态码：200

天猫精灵接口

POST /api/tomi

接收天猫精灵的语音指令

⚠️ 如果配置了 TOMI_SECRET_KEY，需要在请求头中携带密钥

请求头（如果配置了 TOMI_SECRET_KEY）：

X-Tomi-Secret: your_secret_key

密钥值必须与 TOMI_SECRET_KEY 环境变量一致

请求体（示例）：

                                    {
  "payload": {
    "intent": {
      "name": "TurnOnLight"
    }
  }
}
                                

响应：

                                    {
  "returnCode": "0",
  "returnValue": {
    "resultType": "RESULT",
    "executeCode": "SUCCESS",
    "gwCommands": [{
      "commandDomain": "AliGenie.Speaker",
      "commandName": "Speak",
      "payload": {
        "type": "text",
        "text": "好的，已为您打开灯光"
      }
    }]
  }
}
                                

状态码：200

系统会自动：提取意图标识 → 查找映射 → 调用 Home Assistant API → 返回回复内容

安全提示：强烈建议在生产环境中配置 TOMI_SECRET_KEY 环境变量，并在天猫精灵平台配置相同的请求头。详细配置方法请参考天猫精灵平台配置指南。

GET /aligenie/:filename

天猫精灵域名校验文件

✓ 无需认证

用于天猫精灵开放平台的域名校验。文件名和内容通过环境变量 ALIGENIE_NAME 和 ALIGENIE_CONTENT 配置。

错误码

状态码	错误码	说明
400	MISSING_PASSWORD	密码不能为空
401	INVALID_PASSWORD	密码错误
401	UNAUTHORIZED	未授权访问，请先登录
404	-	资源不存在
500	SERVER_ERROR	服务器内部错误