怎么接入20W 远程控制 TTS 语音壁挂音箱以实现HTTP接口文本推送播报_解决方案

CATALOG

芯步这款20W壁挂音箱的HTTP接口对接其实很简单——核心就是调用一个接口，把你要说的话以文本形式发给它，音箱就会自动合成语音播报出来。下面我整理了完整的对接流程、代码示例和一些踩坑经验。

一、准备工作：你得先拿到这三样东西

在写代码之前，需要先去芯步的官方控制台（Open Platform）搞到三个关键凭证，这相当于你操作设备的“账号密码”：

AppID：你的应用ID，标识你是哪个开发者。
AppSecret：你的应用密钥，千万别泄露在网页前端代码里，最好放在后端。
Device ID：就是音箱底部的那个设备编号，或者你在控制台看到的设备ID（比如 820720）。

二、接口地址与核心逻辑

这款音箱最方便的地方就是它直接走 HTTP协议，不需要额外的网关，接上WiFi就能用。

请求地址https://api.thingboot.com/{你的AppID}/device/control/?sign={签名}&ts={时间戳}
核心逻辑只要是支持HTTP请求的编程语言（Java, Python, PHP, Node.js, C# 等等）都能接入。它的原理是，你的服务器把要播报的文字塞进 order 参数里，通过POST请求发给芯步的云平台，云平台再把指令推送给你家那个连接WiFi的音箱。

三、实战：两步实现文本推送播报

这是最关键的部分，主要分两步：算签名 和 发指令。

第一步：计算签名

芯步的接口为了安全，要求每一次请求都要带签名，算法稍微有点绕，但照着套公式就行

sign = md5( md5(AppSecret) + ts )

先把你拿到的 AppSecret 做一次MD5加密。
把加密后的结果，再拼接上当前的时间戳 ts（单位是秒）。
把拼接后的字符串再做一次MD5加密，得到的结果就是 sign。

（稍微口语化：就是嵌套了两层MD5，中间是把第一次MD5的结果和ts拼在一起。）

第二步：下发播报指令

签名算好之后，就往那个接口地址发送一个 POST 请求，格式必须是 JSON。

关键参数（Order里面的命令）：对于这款20W音箱，让它说话的命令格式是 {"play:gbk:16":"你要说的话"}。

play:gbk:16：这是固定的，代表文本编码格式和播放模式，照着写就行，不用深究含义。
value：引号里放你想要的文本。

请求体示例：

四、代码写出来长啥样？ (Python 版示例)

给你贴一段可以直接拿去测试的Python代码，稍微口语化解释一下每一行是干嘛的：

import requests
import time
import hashlib
import json

# 1. ----- 配置区 (你在这里填上你自己的三个值) -----
APP_ID = "你的AppID"          # 比如 "qtyVWcgeMq"
APP_SECRET = "你的AppSecret"  # 比如 "abc123..."
DEVICE_ID = "你的设备ID"       # 比如 "820720"

# 2. ----- 业务逻辑:计算签名 -----
ts = int(time.time())  # 获取当前时间戳
# 官方规则: md5( md5(AppSecret) + ts )
step1 = hashlib.md5(APP_SECRET.encode()).hexdigest()  # 第一次MD5
step2 = step1 + str(ts)                               # 拼接时间戳
sign = hashlib.md5(step2.encode()).hexdigest()        # 第二次MD5

# 3. ----- 拼接URL -----
url = f"https://api.thingboot.com/{APP_ID}/device/control/?sign={sign}&ts={ts}"

# 4. ----- 包装要播报的数据 -----
# 你要让音箱说啥？
text_to_say = "工单号70534，请尽快处理。"
payload = {
    "device": DEVICE_ID,
    "order": {"play:gbk:16": text_to_say}  # 核心指令
}

# 5. ----- 发送请求 -----
headers = {'Content-Type': 'application/json'}
response = requests.post(url, headers=headers, data=json.dumps(payload))

# 6. ----- 看结果 -----
if response.status_code == 200 and response.json().get('code') == 200:
    print("指令已送达，音箱即将播报！")
else:
    print("出错了:", response.text)

五、避坑指南

实际开发中，你可能遇到一些“明明感觉对了但就是不响”的情况，主要排查这几点：

HTTP 200 不等于播报成功：接口返回 200 只代表服务器收到了指令，不代表音箱收到了。如果没声音，先检查音箱是否在控制台显示“在线”。
中文字符乱码：如果你的文本里有生僻字或者特殊符号，确保你的代码文件编码是 UTF-8，并且在发送请求时，Content-Type 设成了 application/json; charset=utf-8。
支持多设备控制：如果你有一整层楼都是这种音箱，可以在 device 字段里用 | 或者 , 隔开设备ID，一次性让所有音箱同时喊话。
私有化部署：如果你们公司网络环境要求高，不能走公网，这款设备也支持私有化部署，把请求地址换成你们自己的局域网服务器地址就行，接口格式完全一样。

六、还可以怎么玩？

除了单纯播报文字，你还可以在 order 里加参数控制音箱的音色（男声/女声）、音量、语速等。

例如，你希望声音大一点：

（注：音量范围一般是 0-9，数字越大越响。）

总结一下：拿到 AppID/Secret/DeviceID -> 算个嵌套MD5签名 -> 组装JSON丢过去 -> 完事。整个过程熟练的话，后端开发大概10分钟就能搞定接入。