小智Pro

Appearance

远程控制API ​

INFO

本文档描述了一套完整的远程控制设备的API接口，支持查看MCP工具列表、唤醒、重启、消息发送、获取设备信息、设备设置等功能。

1. 获取MCP工具列表 ​

基本信息 ​

  • 接口路径: /xiaozhi/tools/list
  • 请求方法: POST
  • 认证方式: API Key

请求参数 ​

json
{
  "device_id": "string",
  "common": "boolean"
}

参数说明:

  • device_id (string, required): 设备 MAC 地址，例如：00:11:22:33:44:55
  • common (boolean, optional, default=true):
    • true: 对应设备端 mcp_server.cc 中的 CommonTools 列表
    • false: 对应设备端 mcp_server.cc 中的 UserOnlyTools 列表

响应示例 ​

json
{
  "code": 200,
  "msg": "OK",
  "data": {
    "tools": [
      "self.get_system_info",
      "self.reboot",
      "self.upgrade_firmware",
      "self.screen.get_info",
      "self.screen.snapshot",
      "self.screen.preview_image",
      "self.assets.set_download_url",
      "self.wake_up",
      "self.send_command",
      "self.get_device_state"
    ]
  }
}

2. 远程控制接口 ​

用于调用设备端指定的工具。

基本信息 ​

  • 接口路径: /xiaozhi/tools/call
  • 请求方法: POST
  • 认证方式: API Key

请求参数 ​

json
{
  "device_id": "string",
  "name": "string",
  "arguments": {}
}

参数说明:

  • device_id (string, required): 设备 MAC 地址，例如：00:11:22:33:44:55
  • name (string, required): 工具名称
  • arguments (object, optional): 工具调用参数，默认为空

响应示例 ​

以唤醒请求为例，返回结果如下：

json
{
  "code": 200,
  "msg": "OK",
  "data": {
    "content": [
      {
        "type": "text",
        "text": "true"
      }
    ],
    "isError": false
  }
}

3. 远程控制接口示例 ​

本部分列举常见的远程控制接口的调用示例。

  • 工具名称 name 请参考：1. 获取MCP工具列表
  • 工具调用参数 arguments 请参考：设备端 MCP 工具定义。

3.0 获取系统信息 ​

请求参数:

json
{
  "device_id": "string",
  "name": "self.get_system_info",
  "arguments": {}
}

响应示例:

json
{
  "code": 200,
  "msg": "OK",
  "data": {
    "content": [
      {
        "type": "text",
        "text": "{\"version\":2,\"language\":\"zh-CN\",\"flash_size\":16777216,\"minimum_free_heap_size\":\"7116772\"}}"
      }
    ],
    "isError": false
  }
}

3.1 重启设备 ​

请求参数:

json
{
  "device_id": "string",
  "name": "self.reboot",
  "arguments": {}
}

响应示例:

json
{
  "code": 200,
  "msg": "OK",
  "data": {
    "content": [
      {
        "type": "text",
        "text": "true"
      }
    ],
    "isError": false
  }
}

3.2 唤醒设备 ​

请求参数:

json
{
  "device_id": "string",
  "name": "self.wake_up",
  "arguments": { "reason": "你好小智" }
}

3.3 发送指令（短文本） ​

请求参数:

json
{
  "device_id": "string",
  "name": "self.send_command",
  "arguments": { "text": "定个闹钟" }
}

DANGER

注：

  • 发送指令要求：请先调用唤醒设备接口让设备进入Listening状态，否则会调用失败；
  • 发送指令（短文本）要求：text 字段字符数小于 10，否则会调用失败；
  • 长文本请使用 发送指令（长文本）接口。

3.4 发送指令（长文本） ​

暂不开放，有需求联系群主。

3.5 获取设备对话状态 ​

请求参数:

json
{
  "device_id": "string",
  "name": "self.get_device_state",
  "arguments": {}
}

响应示例:

json
{
  "code": 200,
  "msg": "OK",
  "data": {
    "content": [
      {
        "type": "text",
        "text": "{\"state\":\"idle\"}"
      }
    ],
    "isError": false
  }
}

参数说明:

  • state (string): 设备当前对话状态，可能的值包括：
    • unknown - 未知状态
    • starting - 启动中
    • wifi_configuring - WiFi 配置中
    • idle - 空闲
    • connecting - 连接中
    • listening - 监听中（正在对话）
    • speaking - 播报中
    • upgrading - 升级中
    • activating - 激活中
    • audio_testing - 音频测试中
    • alarm - 闹钟响铃中
    • fatal_error - 致命错误

3.6 获取设备硬件状态 ​

请求参数:

json
{
  "device_id": "string",
  "name": "self.get_device_status",
  "arguments": {}
}

响应示例:

json
{
  "code": 200,
  "msg": "OK",
  "data": {
    "content": [
      {
        "type": "text",
        "text": "{\"audio_speaker\":{\"volume\":80},\"screen\":{\"brightness\":80,\"theme\":\"light\"},\"battery\":{\"level\":95,\"charging\":false},\"network\":{\"type\":\"wifi\",\"ssid\":\"12_404\",\"signal\":\"medium\"}}"
      }
    ],
    "isError": false
  }
}

3.7 调整音量 ​

请求参数:

json
{
  "device_id": "string",
  "name": "self.audio_speaker.set_volume",
  "arguments": { "volume": 50 }
}

参数说明:

  • volume (int, required): 音量，取值范围 0-100

3.8 调整屏幕亮度 ​

请求参数:

json
{
  "device_id": "string",
  "name": "self.screen.set_brightness",
  "arguments": { "brightness": 50 }
}

参数说明:

  • brightness (int, required): 屏幕亮度，取值范围 0-100

3.9 拍照答疑 ​

WARNING

适用于接入摄像头的设备。

请求参数:

json
{
  "device_id": "string",
  "name": "self.camera.take_photo",
  "arguments": { "question": "这道题怎么做" }
}

参数说明:

  • question (string, required)：基于拍照的图片，回答你的问题

3.10 开关灯光 ​

WARNING

适用于接入 Led 灯的设备。

请求参数:

json
{
  "device_id": "string",
  "name": "self.led.turn_on",
  "arguments": {}
}
json
{
  "device_id": "string",
  "name": "self.led.turn_off",
  "arguments": {}
}
json
{
  "device_id": "string",
  "name": "self.led.set_brightness",
  "arguments": { "brightness": 50 }
}

3.11 更多 ​

更多接口需求，可联系群主定制化开发。