开放 API 调用示例

开放 API 使用当前账户创建的 API Key 鉴权，可读取本人车辆及实时车况数据。

调用前准备

登录 Xiaomi EV Mate。
进入 个人中心 → 基本信息 → 开放 API。
创建 API Key，并立即复制保存完整密钥。完整密钥只展示一次。
准备 Xiaomi EV Mate 的访问地址，例如 https://ev.example.com。

每个用户最多同时保留 5 个有效 API Key；已过期或已禁用的 Key 不占用有效名额。已过期或已禁用的记录可以在管理页面删除。

下文使用以下变量，执行命令前请替换为自己的服务地址和 API Key：

BASE_URL="https://ev.example.com"
API_KEY="xm_sk_请替换为完整密钥"

所有请求都必须通过请求头传递密钥：

Authorization: Bearer <API_KEY>

请勿把 API Key 放在 URL 查询参数、公开仓库、日志或截图中。

1. 获取车辆

先获取当前 API Key 所属用户的车辆列表，并记录响应中的内部车辆 id。后续接口使用这个 id，不是小米侧车辆编号。

curl --request GET \
  --url "${BASE_URL}/api/openapi/v1/vehicles" \
  --header "Authorization: Bearer ${API_KEY}" \
  --header "Accept: application/json"

响应示例：

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "carName": "我的车辆",
      "carModel": "SU7"
    }
  ]
}

2. 获取车况

将路径中的 ${VEHICLE_ID} 替换为车辆列表返回的车辆 id。

curl --request GET \
  --url "${BASE_URL}/api/openapi/v1/vehicles/status/${VEHICLE_ID}" \
  --header "Authorization: Bearer ${API_KEY}" \
  --header "Accept: application/json"

响应示例：

{
  "code": 200,
  "data": {
    "vehicleId": 1,
    "vehicleName": "我的车辆",
    "batteryLevel": 82,
    "remainingRange": 536,
    "sentryModeEnabled": false,
    "charging": false,
    "observedAt": "2026-07-27 10:30:00"
  }
}

主要字段：

batteryLevel：当前电量百分比。
remainingRange：当前剩余续航，单位为公里。
sentryModeEnabled：哨兵模式是否开启。
charging：是否正在充电，只有真实充电中才为 true。
observedAt：本次实时车况的观测时间，格式为 yyyy-MM-dd HH:mm:ss。

3. 检测充电

将路径中的 ${VEHICLE_ID} 替换为车辆列表返回的车辆 id。

curl --request GET \
  --url "${BASE_URL}/api/openapi/v1/charging/detect/${VEHICLE_ID}" \
  --header "Authorization: Bearer ${API_KEY}" \
  --header "Accept: application/json"

响应示例：

{
  "code": 200,
  "data": {
    "vehicleId": 1,
    "charging": true,
    "chargeStateDescription": "充电中",
    "detectedAt": "2026-07-27 10:31:00"
  }
}

4. iOS 快捷指令

可直接安装 Xiaomi EV Mate 快捷指令，用于查询车辆实时车况和检测充电状态。

首次运行时，根据提示填写 Xiaomi EV Mate 服务地址和当前账户创建的 API Key。配置保存在用户自己的 iCloud Drive 中，不包含在快捷指令分享链接内；账户只有一辆车时自动使用该车辆，多辆车时可按车辆名称选择。

首次访问服务域名时，iOS 会显示数据访问授权提示，选择“始终允许”后，后续访问同一域名通常不会重复提示。

请勿分享包含个人配置的文件或截图 API Key；怀疑密钥泄露时，应立即在开放 API 管理页面禁用并重新创建。

状态码与调用限制

200：请求成功。
401：缺少 API Key，或者密钥无效、已过期、已禁用。
429：请求过于频繁，请稍后再试。
获取车辆接口：每个 API Key 每分钟最多 30 次。
实时车况和充电检测：单个 API Key 每分钟最多 6 次；同一用户所有 Key 合计每小时最多 60 次。

API Key 只能访问所属用户自己的车辆。怀疑密钥泄露时，请立即回到开放 API 管理页面禁用或删除。