设备 OTA

OTA 接口文档

设备使用个人安全密钥和 MAC 地址，获取你名下已审核通过的社区固件。稳定版不用额外请求头；测试版必须带 X-OTA-Channel: test。

接入步骤

1先到个人中心获取 OTA 安全密钥。完整密钥可随时查看；再次获取会使旧密钥立即失效。
2将密钥写入嵌入式代码并烧录到设备。请勿把密钥提交到公开代码仓库或输出到设备日志。
3请求头带上 X-OTA-Key 和 Device-Id。只要稳定版时不要传 X-OTA-Channel；要测试版时必须传 X-OTA-Channel: test。
4请求体里 board.type 填左侧开发板名称，application.name 填固件名称。官方开发板和自己创建的社区开发板都填侧栏里的名称。空格和大小写不影响匹配。
5请求体里 chip_model_name 必填，填设备实际的芯片型号。开发板允许同名不同芯片，板名加芯片才能唯一定位到一块板。

请求地址

方法: POST
只接受 POST。用浏览器直接打开，或发 GET，不会返回固件。
URL: https://admin.metalio.world/xiaozhi/api/firmware-ota/check

请求头

Header	必填 / 可选	Description
X-OTA-Key	必填	个人中心生成的 OTA 安全密钥。只能下载该密钥所属用户发布的固件。
Device-Id	必填	设备 MAC，例如 AA:BB:CC:DD:EE:FF。
X-OTA-Channel	测试版必填	不传或 latest：只返回稳定版。要返回测试版时必须填 test。指定 application.version 时，稳定版和测试版都按版本号精确匹配。
Client-Id	可选	客户端标识，不参与选固件。

请求体

Field	必填 / 可选	Description
board.type	必填	左侧开发板名称，例如 Metalio E-Ink4 或 Metalio Claw4。忽略空格和大小写，MetalioE-Ink4 同样可以匹配。
chip_model_name	必填	设备实际芯片型号，例如 esp32s3 或 bk7258。忽略大小写和连字符，ESP32-S3 与 esp32s3 视为同一颗。开发板同名时靠它区分。
application.name	必填	固件名称，必须和「我的固件」里的标题一致，例如 ai。
application.version	可选	不传：返回当前通道里最高的可用版本。传入：只返回版本号完全相同的那一版。

获取最新稳定版

不要传 X-OTA-Channel，也不要传 application.version。只返回审核通过的稳定版。

{
  "chip_model_name": "esp32s3",
  "board": {
    "type": "Metalio E-Ink4"
  },
  "application": {
    "name": "Metalio-WhiteAI"
  }
}

获取测试版

请求头必须增加 X-OTA-Channel: test。此时稳定版和测试版都会参与比较，返回其中最高的可用版本。

X-OTA-Channel: test

{
  "chip_model_name": "esp32s3",
  "board": {
    "type": "Metalio E-Ink4"
  },
  "application": {
    "name": "Metalio-WhiteAI"
  }
}

获取指定版本

传入 application.version，服务端按版本号完全匹配。这一版无论是稳定版还是测试版都可以下载。

{
  "chip_model_name": "esp32s3",
  "board": {
    "type": "Metalio E-Ink4"
  },
  "application": {
    "name": "Metalio-WhiteAI",
    "version": "1.2.0"
  }
}

完整请求示例

不要传 X-OTA-Channel，也不要传 application.version。只返回审核通过的稳定版。

curl -X POST 'https://admin.metalio.world/xiaozhi/api/firmware-ota/check' \
  -H 'Device-Id: AA:BB:CC:DD:EE:FF' \
  -H 'X-OTA-Key: fw_ota_u1024_your_random_secret' \
  --json '{"chip_model_name": "esp32s3","board": {"type": "Metalio E-Ink4"},"application": {"name": "Metalio-WhiteAI"}}'

请求头必须增加 X-OTA-Channel: test。此时稳定版和测试版都会参与比较，返回其中最高的可用版本。

curl -X POST 'https://admin.metalio.world/xiaozhi/api/firmware-ota/check' \
  -H 'Device-Id: AA:BB:CC:DD:EE:FF' \
  -H 'X-OTA-Key: fw_ota_u1024_your_random_secret' \
  -H 'X-OTA-Channel: test' \
  --json '{"chip_model_name": "esp32s3","board": {"type": "Metalio E-Ink4"},"application": {"name": "Metalio-WhiteAI"}}'

成功响应示例

设备通常只需要读取 firmware.version 与 firmware.url。

{
  "has_update": true,
  "firmware": {
    "version": "1.2.0",
    "url": "https://admin.metalio.world/OTA/example.bin",
    "size": 1488978,
    "version_status": "latest",
    "firmware_name": "Metalio-WhiteAI"
  }
}

错误响应

HTTP	error	Description
401	X-OTA-Key is required	没有带密钥。
401	invalid OTA access key	密钥不存在或已失效。重新获取密钥后，旧密钥立即失效。
400	Device-Id is required and must be a MAC address	缺少 Device-Id，或不是 AA:BB:CC:DD:EE:FF 这种 MAC。
400	board.type is required	请求体没有开发板名称。
400	application.name is required	请求体没有固件名称。
400	chip_model_name is required	请求体没有芯片型号。
404	no board matches board.type and chip_model_name	有多块同名开发板，但没有一块的芯片和上报芯片一致。检查上报的芯片型号，或确认固件挂在哪块板下。
404	firmware not found	当前密钥所属用户下，这块开发板没有这份固件名称。
404	available firmware version not found	没传版本号，但当前通道没有可下发版本。测试版没带 X-OTA-Channel: test 时也会是这个错误。
404	requested firmware version not found	传了 application.version，但没有审核通过且带固件文件的同名版本。
409	firmware OTA is disabled	这份固件关闭了 OTA 开关。整体下线、版本下线不会触发这个错误。
409	firmware download URL is unavailable	版本记录在，但下载地址生成失败。
409	firmware name matches more than one firmware on this board	同一用户、同一块板上命中了多份同名固件。

匹配与安全规则

开发板由 board.type 加 chip_model_name 共同定位。开发板允许同名不同芯片，所以芯片型号必填。
有多块同名开发板时，只在芯片一致的那块板下找固件；芯片对不上任何一块时返回 404，不会随便挑一块下发。
board.type 只对应一块开发板时，芯片不参与筛选，只在不一致时记服务端日志，不影响下发。
同一块开发板可以有多份固件，靠 application.name 区分。同一用户在同一块板上的固件名不能重复。
密钥只能访问其所属用户发布的固件，不能跨用户下载。
整体下线和版本下线只影响公开仓库是否展示，不影响携带所有者密钥的设备拉取。
版本必须审核通过，并且已经有固件文件。审核中、已拒绝或没有文件时返回 404。
不传 X-OTA-Channel 时，测试版不会被返回。
找不到固件或没有可下发版本时返回 404；OTA 开关关闭或下载地址不可用时返回 409，成功响应不会带空 URL。
密钥缺失或无效时返回 401。缺少 board.type、chip_model_name、application.name，或 Device-Id 不是合法 MAC 时返回 400。

设备 OTA

OTA 接口文档

设备使用个人安全密钥和 MAC 地址，获取你名下已审核通过的社区固件。稳定版不用额外请求头；测试版必须带 X-OTA-Channel: test。

接入步骤

1先到个人中心获取 OTA 安全密钥。完整密钥可随时查看；再次获取会使旧密钥立即失效。
2将密钥写入嵌入式代码并烧录到设备。请勿把密钥提交到公开代码仓库或输出到设备日志。
3请求头带上 X-OTA-Key 和 Device-Id。只要稳定版时不要传 X-OTA-Channel；要测试版时必须传 X-OTA-Channel: test。
4请求体里 board.type 填左侧开发板名称，application.name 填固件名称。官方开发板和自己创建的社区开发板都填侧栏里的名称。空格和大小写不影响匹配。
5请求体里 chip_model_name 必填，填设备实际的芯片型号。开发板允许同名不同芯片，板名加芯片才能唯一定位到一块板。

前往个人中心获取安全密钥

请求地址

方法: POST
只接受 POST。用浏览器直接打开，或发 GET，不会返回固件。
URL: https://admin.metalio.world/xiaozhi/api/firmware-ota/check

请求头

Header	必填 / 可选	Description
X-OTA-Key	必填	个人中心生成的 OTA 安全密钥。只能下载该密钥所属用户发布的固件。
Device-Id	必填	设备 MAC，例如 AA:BB:CC:DD:EE:FF。
X-OTA-Channel	测试版必填	不传或 latest：只返回稳定版。要返回测试版时必须填 test。指定 application.version 时，稳定版和测试版都按版本号精确匹配。
Client-Id	可选	客户端标识，不参与选固件。

请求体

Field	必填 / 可选	Description
board.type	必填	左侧开发板名称，例如 Metalio E-Ink4 或 Metalio Claw4。忽略空格和大小写，MetalioE-Ink4 同样可以匹配。
chip_model_name	必填	设备实际芯片型号，例如 esp32s3 或 bk7258。忽略大小写和连字符，ESP32-S3 与 esp32s3 视为同一颗。开发板同名时靠它区分。
application.name	必填	固件名称，必须和「我的固件」里的标题一致，例如 ai。
application.version	可选	不传：返回当前通道里最高的可用版本。传入：只返回版本号完全相同的那一版。

获取最新稳定版

不要传 X-OTA-Channel，也不要传 application.version。只返回审核通过的稳定版。

{
  "chip_model_name": "esp32s3",
  "board": {
    "type": "Metalio E-Ink4"
  },
  "application": {
    "name": "Metalio-WhiteAI"
  }
}

获取测试版

请求头必须增加 X-OTA-Channel: test。此时稳定版和测试版都会参与比较，返回其中最高的可用版本。

X-OTA-Channel: test

{
  "chip_model_name": "esp32s3",
  "board": {
    "type": "Metalio E-Ink4"
  },
  "application": {
    "name": "Metalio-WhiteAI"
  }
}

获取指定版本

传入 application.version，服务端按版本号完全匹配。这一版无论是稳定版还是测试版都可以下载。

{
  "chip_model_name": "esp32s3",
  "board": {
    "type": "Metalio E-Ink4"
  },
  "application": {
    "name": "Metalio-WhiteAI",
    "version": "1.2.0"
  }
}

完整请求示例

不要传 X-OTA-Channel，也不要传 application.version。只返回审核通过的稳定版。

curl -X POST 'https://admin.metalio.world/xiaozhi/api/firmware-ota/check' \
  -H 'Device-Id: AA:BB:CC:DD:EE:FF' \
  -H 'X-OTA-Key: fw_ota_u1024_your_random_secret' \
  --json '{"chip_model_name": "esp32s3","board": {"type": "Metalio E-Ink4"},"application": {"name": "Metalio-WhiteAI"}}'

请求头必须增加 X-OTA-Channel: test。此时稳定版和测试版都会参与比较，返回其中最高的可用版本。

curl -X POST 'https://admin.metalio.world/xiaozhi/api/firmware-ota/check' \
  -H 'Device-Id: AA:BB:CC:DD:EE:FF' \
  -H 'X-OTA-Key: fw_ota_u1024_your_random_secret' \
  -H 'X-OTA-Channel: test' \
  --json '{"chip_model_name": "esp32s3","board": {"type": "Metalio E-Ink4"},"application": {"name": "Metalio-WhiteAI"}}'

成功响应示例

设备通常只需要读取 firmware.version 与 firmware.url。

{
  "has_update": true,
  "firmware": {
    "version": "1.2.0",
    "url": "https://admin.metalio.world/OTA/example.bin",
    "size": 1488978,
    "version_status": "latest",
    "firmware_name": "Metalio-WhiteAI"
  }
}

错误响应

HTTP	error	Description
401	X-OTA-Key is required	没有带密钥。
401	invalid OTA access key	密钥不存在或已失效。重新获取密钥后，旧密钥立即失效。
400	Device-Id is required and must be a MAC address	缺少 Device-Id，或不是 AA:BB:CC:DD:EE:FF 这种 MAC。
400	board.type is required	请求体没有开发板名称。
400	application.name is required	请求体没有固件名称。
400	chip_model_name is required	请求体没有芯片型号。
404	no board matches board.type and chip_model_name	有多块同名开发板，但没有一块的芯片和上报芯片一致。检查上报的芯片型号，或确认固件挂在哪块板下。
404	firmware not found	当前密钥所属用户下，这块开发板没有这份固件名称。
404	available firmware version not found	没传版本号，但当前通道没有可下发版本。测试版没带 X-OTA-Channel: test 时也会是这个错误。
404	requested firmware version not found	传了 application.version，但没有审核通过且带固件文件的同名版本。
409	firmware OTA is disabled	这份固件关闭了 OTA 开关。整体下线、版本下线不会触发这个错误。
409	firmware download URL is unavailable	版本记录在，但下载地址生成失败。
409	firmware name matches more than one firmware on this board	同一用户、同一块板上命中了多份同名固件。

匹配与安全规则

开发板由 board.type 加 chip_model_name 共同定位。开发板允许同名不同芯片，所以芯片型号必填。
有多块同名开发板时，只在芯片一致的那块板下找固件；芯片对不上任何一块时返回 404，不会随便挑一块下发。
board.type 只对应一块开发板时，芯片不参与筛选，只在不一致时记服务端日志，不影响下发。
同一块开发板可以有多份固件，靠 application.name 区分。同一用户在同一块板上的固件名不能重复。
密钥只能访问其所属用户发布的固件，不能跨用户下载。
整体下线和版本下线只影响公开仓库是否展示，不影响携带所有者密钥的设备拉取。
版本必须审核通过，并且已经有固件文件。审核中、已拒绝或没有文件时返回 404。
不传 X-OTA-Channel 时，测试版不会被返回。
找不到固件或没有可下发版本时返回 404；OTA 开关关闭或下载地址不可用时返回 409，成功响应不会带空 URL。
密钥缺失或无效时返回 401。缺少 board.type、chip_model_name、application.name，或 Device-Id 不是合法 MAC 时返回 400。