芯步智能音柱的HTTP接口采用双MD5签名机制，核心是构造正确的order命令字段——文本推送使用{"play:gbk:16":"要播报的内容"}格式。以下是完整的对接方案。

一、 概述与准备

1.1 适用产品

本方案主要针对芯步 智能语音音柱系列（涵盖10W、30W、PRO-60W等型号）。该系列产品的核心优势在于免录音、免合成，业务系统直接推送文本即可实现实时语音播报。

1.2 核心准备数据

在开始对接前，请登录[芯步开放平台/控制台]获取以下关键信息：

• AppID（应用ID） ：用于标识哪个应用/项目在调用接口。

• AppSecret（开发者密码） ：用于计算接口签名，请妥善保管，严禁硬编码在前端。

• Device ID（设备ID） ：音柱设备的唯一标识（通常在设备标签或控制台设备列表查看）。

1.3 技术原理

• 通信协议：HTTPS（推荐） / HTTP。

• 请求方法：POST。

• 数据格式application/json 或 application/x-www-form-urlencoded。

• 核心指令格式：文本播报采用特定的JSON结构 {"play:gbk:16":"要播报的文字"}。

二、 接口鉴权与签名机制

芯步的接口采用“动态签名”机制以防止接口被篡改。鉴权参数通过 URL Query 传递，而非 Header。

2.1 签名计算公式

这是对接中最关键的一步，签名逻辑如下：

1. 获取当前Unix时间戳（秒级），记为 ts。

2. step1_md5 = md5(AppSecret)

3. step2_str = step1_md5 + ts

4. sign = md5(step2_str)

公式说明sign = MD5( MD5(AppSecret) + ts )

2.2 请求地址结构

POST https://api.thingboot.com/{AppID}/device/control/?sign={sign}&ts={ts}

2.3 示例计算（伪代码）

假设 AppSecret = "abc123"，ts = 1735689600

1. MD5("abc123") = "e99a18c428cb38d5f260853678922e03"

2. 拼接后 = "e99a18c428cb38d5f260853678922e03" + "1735689600"

3. 最终sign = MD5("e99a18c428cb38d5f260853678922e031735689600")

三、 核心功能实现：HTTP文本推送

这是业务系统最常用的功能——让音柱“说话”。

3.1 请求体参数（Body）

• device：字符串，目标设备ID（支持批量传参，多个ID用英文逗号隔开）。

• order：JSON字符串，这是控制动作的核心。

  • 普通文本播报命令为：{"play:gbk:16":"播报内容"}。

  • 说明play:gbk:16 表示GBK编码下的TTS（文字转语音）播报，数字16通常代表默认音量或优先级，常规使用此格式即可。

3.2 请求示例

场景：让设备ID为 YZ6688 的音柱播报“你好，欢迎光临”。

请求包体

3.3 多语言及代码示例（Python）

以下是一个完整的Python对接示例，展示了动态构造请求的全过程：

四、 高级控制与参数调节

除了简单的文本推送，30W音柱还支持通过修改 order 对象来实现个性化控制。

4.1 音量、语速与音色调节

可以在播报的同时，或者单独发送指令来调节设备状态。具体命令取决于产品的固件版本，通常在order中包含 vol（音量0-15）、speed（速度）、voice（音色）等参数。

常用控制命令示例

• 设置音量{"vol": 10} （假设范围为0-15）

• 组合播报：部分固件支持链式操作，但标准稳定做法是分开发送，或在支持的命令结构中包含参数。

4.2 支持的数字与多音字读法

接口内置了智能处理引擎，直接推送以下内容会自动优化播报效果：

• 金额"订单金额199.9元" -> 读作 “一百九十九点九元”。

• 手机号"联系13800138000" -> 读作 “幺三八零零幺三八零零零”。

• 多音字：在文本中替换为同音词（如“重庆”读作“拆庆”效果更好），系统虽有纠错但依赖上下文。

4.3 批量/分组播报

如果需要同时在多个区域（如多个仓库、多个楼层）播报，可以在 device 参数中用逗号分隔设备ID：

此时，所有在线的指定音柱将同步发声，实现广播效果。

五、 常见问题排查（FAQ）

5.1 返回签名错误（sign_error）

• 现象：服务器返回签名无效。

• 排查

  1. 确认 AppSecret 严格一致（注意大小写）。

  2. 确认时间戳 ts 是否为秒级（10位数字），且与服务器时间误差不宜过大（通常需在5分钟内，可通过NTP同步服务器时间）。

  3. 确认拼接顺序：md5(md5(secret) + ts)，不要搞反了顺序。

5.2 返回设备不在线

• 现象：设备离线错误。

• 排查

  1. 30W音柱使用WiFi 2.4G联网，确认设备所处环境WiFi信号强且支持2.4G频段（不支持5G WiFi）。

  2. 音柱支持“自动重连”，如果刚上电，请等待几秒网络连接完成。

5.3 播报乱码或中断

• 原因：中文编码问题。

• 解决：请一定要确保 order 中的 play:gbk:16 键值对中的文本是 GBK编码 或 UTF-8（绝大部分云平台标准接口已适配UTF-8，但如果发现乱码，尝试将系统文本转码为GBK再进行Base64或直接传输，具体看设备固件更新日志。根据文档，play:gbk:16 显式要求GBK，请求发送前对文本内容进行 .encode('gbk') 处理）。

5.4 关于私有化部署（私有云）

如果你的系统需要在内网环境运行，不支持访问公网，芯步支持私有化部署。

• 操作：采购硬件时申请私有化固件。

• 对接：API地址将从 api.thingboot.com 变更为你指定的本地服务器IP地址，签名算法不变。

方案总结：对接芯步30W语音音柱的核心在于构造正确的签名和组装正确的Order JSON串。一旦签名验证通过，通过HTTP POST请求向音柱推送文本即可实现毫秒级的语音响应，无需复杂的音频处理流程。