云信智能硬件 OTA 请求接口

更新时间： 2026/09/14 10:29:44

云信智能硬件 OTA 请求接口主要处理智能硬件设备的 OTA（Over-The-Air）升级请求。设备通过发送设备信息和当前固件版本，云信服务器将返回最新的固件版本和下载链接（如果有更新）。返回信息中，还增加了 MQTT 和 Websocket 服务器信息，设备激活码。

主要功能

设备调用 OTA URL 时，上报设备身份、当前固件版本、板型和能力信息。服务端根据设备状态返回以下内容：

功能	返回字段	说明
设备激活	`activation`	未激活或未绑定时返回激活码和提示信息
MQTT 配置	`mqtt`	返回 MQTT 服务地址、客户端 ID、鉴权凭证及主题
WebSocket 配置	`websocket`	返回 WebSocket 地址和连接 Token
固件检查	`firmware`	返回目标固件版本、下载地址和 MD5
智能体配置	`agent`	返回打断模式、云音乐权限等业务配置
服务端时间	`server_time`	返回时间戳和时区，用于设备校时

整体关系

flowchart TD
    A["设备启动"] --> B["采集设备信息"]
    B --> B1["设备 ID / MAC"]
    B --> B2["当前固件版本"]
    B --> B3["板型和芯片信息"]
    B --> B4["设备能力"]

    B --> C["调用 OTA URL"]

    C --> D{"是否返回 activation"}

    D -->|"是"| E["展示激活码或激活提示"]
    E --> F["用户完成设备激活和智能体绑定"]
    F --> C

    D -->|"否"| G["解析 OTA 返回配置"]

    G --> H["连接配置"]
    G --> I["智能体和能力配置"]
    G --> J["固件版本信息"]
    G --> K["服务端时间"]

    H --> L{"选择设备接入方式"}

    L -->|"嵌入式 NERTC SDK Lite 模式"| M["使用 OTA 返回的 mqtt 参数初始化协议"]
    M --> N["通过嵌入式 SDK 建立 AI 对话 Session"]

    L -->|"嵌入式 NERTC SDK Normal / PTT 模式"| O["按 SDK 流程获取 Token、Channel 和 UID"]
    O --> N

    L -->|"WebSocket"| P["使用 websocket.url 建立连接"]
    P --> Q["按照 WebSocket 文档传入 app-key 和 token"]
    Q --> R["发送 start 初始化会话"]
    R --> S["传输音频、文本和事件"]

    I --> T["应用打断模式、云音乐权限等配置"]

    J --> U{"是否存在可升级版本"}
    U -->|"是"| V["通过 firmware.url 下载固件"]
    V --> W["校验 MD5"]
    W --> X["安装固件并重启"]
    U -->|"否"| Y["继续使用当前固件"]

    K --> Z["设备校时"]

请求地址

硬件设备烧录配置的 OTA 地址，请配置为以下格式，其中 appkey 为您在网易云信创建应用时获得的应用密钥 AppKey，详情请参考接入概述。

https://nrtc.netease.im/v1/ota?appkey=eca2***200359

请求信息

请求头部分重要参数

参数	类型	说明	示例
`Device-Id`	String	设备的 MAC 地址，服务器返回的 MQTT 信息会依赖该字段。	"14:c1:9f:3b:42:c8"
`Client-Id`	String	设备 client id，服务器返回的 MQTT 信息会依赖该字段。	"876a0031-d2a2-46b5-a7dd-3bb18963752d"

请求体部分重要参数

参数	类型	说明
`mac_address`	String	设备的 MAC 地址。
- `application`	Object	应用信息。
`name`	String	固件分类，例如：设置为 "nertc-b1" 服务端以此认为是网易 B1 开发板设置为 "xiaozhi"，服务端以此认为是开源小智的固件
`device_id`	String	设备 ID，服务器读取设备 ID 的字段以此字段为准，请设置为 MAC 地址，如果该字段为空，那么会读取 `mac_address` 为准。
`version`	String	设备端当前固件版本信息。
- `board`	Object	设备端硬件信息。
`type`	String	设备端的开发板类型，如果使用云信硬件管控台来管理固件，那么该字段值需要在云信硬件管控台提前配置管理，创建产品时，将开发板类型设置为相同字段取值，大小写敏感。

请求示例

常规设备

JSON{
    "version":2,
    "language":"zh-CN",
    "flash_size":16777216,
    "minimum_free_heap_size":"7238764",
    "mac_address":"ac:a7:04:11:ec:20",
    "uuid":"df0b7804-2597-45e9-802b-0b84bb6cf7bd",
    "chip_model_name":"esp32s3",
    "chip_info":{"model":9,"cores":2,"revision":2,"features":18},
    "application":{
        "capabilities":{
            "netease_cloud_music":{
                "support_play":true
            }
        },
        "name":"nertc-b1",
        "version":"0.0.1",
        "board_name":"qudou-42C9",
        "device_id":"14:c1:9f:3b:42:c8",
        "compile_time":"Mar 11 2026T10:39:51Z",
        "idf_version":"v5.4.1-dirty",
        "elf_sha256":"1dd6a8d669d22ad6eb796916ce89f709a2d33e85280c5a85f8f26806e4252651"
    },
    "partition_table":[
        {"label":"nvs","type":1,"subtype":2,"address":36864,"size":16384},
        {"label":"otadata","type":1,"subtype":0,"address":53248,"size":8192},
        {"label":"phy_init","type":1,"subtype":1,"address":61440,"size":4096},
        {"label":"custom","type":1,"subtype":130,"address":65536,"size":131072},
        {"label":"ota_0","type":0,"subtype":16,"address":196608,"size":6291456},
        {"label":"blufi","type":0,"subtype":17,"address":6488064,"size":2621440},
        {"label":"assets","type":1,"subtype":130,"address":9633792,"size":2883584},
        {"label":"model","type":1,"subtype":130,"address":12582912,"size":3145728}
    ],
    "ota":{"label":"ota_0"},
    "display":{"monochrome":false,"width":320,"height":240},
    "board":{
        "type":"esp32-netease-b1-2026",
        "name":"esp32-netease-b1-2026",
        "ssid":"wifissid",
        "rssi":-74,
        "channel":10,
        "ip":"192.168.50.7",
        "mac":"14:c1:9f:3b:42:c8"
    }
}

带云音乐能力设备

JSON{
    ...,
    "application":{
        "capabilities":{
            "netease_cloud_music":{
                "support_play":true
            }
        },
        "name":"xiaozhi",
        ...
    },
    ...
}

有音乐 license：
- support_play 为 true，正常加载 search music tool，不加载 tips music tool。
- support_play 为 false，不加载 search music tool，加载 tips music tool（description 完全同 `search ，实际处理只返回特定回复。）。
没有音乐 license：都不加载。

返回信息

返回体部分重要参数

参数	类型	说明
`activation`	Object	设备激活信息。
`mqtt`	Object	云信 mqtt 服务器地址。
`websocket`	Object	云信 websocket 服务器地址。
`firmware`	Object	固件信息。
`agent`	Object	云信智能体平台的业务信息。

返回示例

设备已绑定时返回

{
    "code":200,
    "message":"success",
    "request_id":"ai7e872053d78944b19e619d90a71e7af9",
    "activation":null,
    "mqtt":{
        "endpoint":"1-95-20-195.netease.im",
        "client_id":"9c8758**********************ee1d@@@45_60_71_86_34_87@@@0fa77422-a772-4fcc-9441-ffcc9774411e",
        "username":"eyJpcCI6IjE4My4xMzYuMTgyLjE0MCJ9",
        "password":"qEyWPj**********************************yuE=",
        "publish_topic":"device-server",
        "subscribe_topic":"null"
    },
    "websocket":{
        "url":"wss://mps.yunxinvcloud.com/?/device_id=45:60:71:86:34:87&app_key=9c8758**********************ee1d",
        "token":"test-token"
    },
    "firmware":{
        "version": "0.0.5",
        "url": "http://yunxin-sre.nos-jd.163yun.com/firmware/0.0.5_202608061408_update-ota.ufw",
        "md5": "d4b9e84ee7fab5f0759ee8a66a73e90d"
    },
    "server_time":{
        "timestamp":1773736014127,
        "timezone_offset":480
    },
    "agent":{
        "pipeline":{
            "interrupt_mode":0
        },
        "netease_cloud_music":{
            "support_music":false,
            "support_play_in_4g":false
        }
    }
}

设备未绑定时返回

{
    "code":200,
    "message":"success",
    "request_id":"aid63fd1bd21254614996662a1ef09dbb6",
    "activation":{
        "message":"请使用小派AI小程序激活\n863277",
        "code":"863277",
        "extra_message":null
    },
    "mqtt":null,
    "websocket":null,
    "firmware":null,
    "server_time":{"timestamp":1773740863156,"timezone_offset":480},
    "agent":null
}

调用流程

前提条件

****：设备激活前，必须先分配授权码，详细流程请参考使用 AI 硬件管控台管理产品、License 和固件。

通过 OTA URL 接入：设备调用 OTA URL 后，服务端检查设备授权码。符合条件时，自动完成激活，并返回后续所需配置。
未完成预激活：根据 activation 返回信息完成激活，激活成功后重新调用 OTA URL。
通过 WebSocket 接入：该接入方式如果未设置 OTA URL，设备必须先调用activate 接口完成激活；激活成功后，继续原有 WebSocket 流程建立连接。

WebSocket WSS 地址仅用于建立会话，不负责预激活。OTA 接入和直接 WebSocket 接入均以设备已完成后台授权为前提。

调用流程

在云信控制台创建应用并获取 AppKey，在智能体平台创建智能体，完成设备授权及设备与智能体的绑定。详情步骤请参考配置智能体。
如需使用云信固件托管，在 AI 硬件管控台上传并发布固件，开发板取值与 OTA 请求接口中的 borad.type 字段保持一致。详情步骤请参考使用 AI 硬件管控台管理产品、License 和固件。
设备启动后，携带设备 ID、Client ID、当前固件版本、板型和能力信息调用 OTA URL。
未激活或未绑定时，设备根据 activation 展示激活码，引导用户完成激活和绑定。
激活完成后重新调用 OTA URL，获取连接配置、智能体配置、能力开关、固件信息和服务端时间。
设备根据接入方式建立 AI 对话连接。
如果返回新固件，设备通过 firmware.url 下载、校验和安装固件。

与嵌入式 NERTC SDK的关系

OTA URL 与嵌入式 NERTC SDK 分别负责不同阶段：

OTA URL：完成启动配置查询、设备激活判断、MQTT 参数下发、智能体配置下发和固件检查。
嵌入式 NERTC SDK：负责建立 AI 对话 Session，传输实时音频并处理打断、字幕和 AI 回复。

嵌入式 SDK 的不同模式与 OTA URL 的关系如下：

SDK 模式	与 OTA URL 的关系
Lite 模式	需要在协议初始化前使用 OTA 返回的 `mqtt` 参数完成相关初始化
Normal 模式	按 SDK 流程使用 Token、Channel、UID 建立会话；当前 OTA 返回结构未定义这些 RTC 入会参数
PTT 模式	按 SDK 流程建立会话，由应用层控制音频发送的开始和结束

因此，不能统一描述为“嵌入式 SDK 必须通过 OTA 获取 RTC 入会参数”。当前明确依赖 OTA 返回值的是 Lite 模式的 MQTT 初始化流程。

与 WebSocket 接入的关系

OTA URL 可以返回：

JSON{
  "websocket": {
    "url": "wss://mps.yunxinvcloud.com/?/device_id=45:60:71:86:34:87&app_key=9c8758**********************ee1d",
    "token": "test-token"
  }
}

设备取得配置后，再按照 WebSocket 接入流程建立会话：

text调用 OTA URL
-> 获取 websocket.url 和 token
-> 建立 WebSocket 连接
-> 发送 start
-> 等待 server_ready
-> 上传音频或文本
-> 接收 ASR、LLM、TTS 和下行音频

OTA URL 本身不是 WebSocket 长连接地址，也不传输会话音频或文本。

WebSocket 建连时，设备 ID 必须与 OTA 请求及智能体平台中的设备 ID 保持一致。app-key 和 token 的传递位置应遵循 WebSocket 接入文档：

device_id：WebSocket URL 参数。
app-key：WebSocket 请求头。
token：启用应用级鉴权时放入 WebSocket 请求头。

此文档是否对你有帮助？

有帮助

去反馈

主要功能
整体关系
请求地址
请求信息
请求头部分重要参数
请求体部分重要参数
请求示例
返回信息
返回体部分重要参数
返回示例
调用流程
前提条件
调用流程
与嵌入式 NERTC SDK的关系
与 WebSocket 接入的关系