怎么接入智能 20W 壁挂远程控制语音音箱以实现自定义语音模板设置_解决方案

CATALOG

芯步的20W智能壁挂音箱开放了HTTP接口，支持通过API直接推送文本进行TTS语音合成。下面从接口原理、签名计算、参数配置到完整代码示例，逐步说明如何实现自定义语音模板。

1. 前置准备：拿到你的“钥匙”

在开始写代码之前，需要先去芯步的开发者后台拿到两样东西，这就像是去银行办业务要先拿号填单一样：

AppID 和 AppSecret：登录芯步控制台，在“开发设置”里就能看到。AppID 像是你的账号名，AppSecret 像是你的密码，这个密码千万不要写在网页前端代码里，只放在后端用。
设备ID：把你的 20W 壁挂音箱通电、联网（它只支持2.4G WiFi），在控制台的设备列表里就能看到这个音箱的编号。

2. 核心原理：其实就是在发微信

这套接口其实就是标准的HTTP POST请求，可以理解为给你的音箱发一条“微信消息”：

地址（URL）：固定的网关地址。
内容（Body）：告诉音箱要说什么话、用什么音量、男声还是女声。

这里有一个稍微麻烦点但很安全的设计：动态签名。为了防止别人乱给你的音箱发指令，每次请求都要带一个临时身份证（Sign），这个身份证是根据 AppSecret + 当前时间戳 经过 MD5 加密算出来的。

签名的算法很简单，分三步：

把 AppSecret 进行一次 MD5 加密，得到字符串 A。
获取当前的 Unix 时间戳（秒），得到字符串 B。
把 A 和 B 拼接起来，再进行一次 MD5 加密，结果就是 Sign。

公式：Sign = md5( md5(AppSecret) + ts )

3. 实现“自定义语音模板”

所谓“自定义模板”，就是把固定的文字和变量（比如温度、用户名、库存数量）拼成一句话，发给音箱。

这个音箱支持芯片级TTS，你不用上传录音，直接发中文过去，它就能用自然的人声读出来。以下是一个标准的请求示例：

请求地址：POST http(s)://api.thingboot.com/{你的AppId}/device/control/?sign={计算出的签名}&ts={当前时间戳}

请求体 JSON：

如何自定义模板？假设你要做一个“仓库缺货提醒”，需要播报：“请注意，商品【可乐】库存仅剩【5】件，请及时补货”。

你的后端代码逻辑应该是：

4. 高级配置：让声音更“好听”

光能说话还不够，还得说得清楚、说得顺耳。在 order 里，除了 play:gbk:16 这个播报指令，还可以附带其他参数来控制音效

调音量"volume": 7 （范围 0-9，9 最大，20W 功率声音很大，室内 5-6 即可）
改音色"voice": 1 （0-女声，1-男声，根据喜好切换）
调语速"speed": 5 （范围 0-9，5 为标准）
插播提示音"ring": 1 （内置 5 种铃声，喊人之前先响铃，效果更好）

一个更完整的请求体示例：

这样写的话，音箱会先响三声特定的铃声，然后用较大的音量、女声播报这段文字。

5. 实操代码示例（Python）

把上面这些串起来，用一个简单的 Python 函数来搞定。你可以把这个函数放到任何后端服务里（比如 Flask、Django 或者是云函数）。

import requests
import time
import hashlib
import json

# 1. 配置你的账号信息
APP_ID = "替换成你的AppID"
APP_SECRET = "替换成你的AppSecret"
DEVICE_ID = "替换成你的设备ID"

def send_voice_message(text, volume=6, voice=0, speed=5):
    """
    发送自定义语音到智能音箱
    """
    # 2. 生成签名 (Sign)
    ts = str(int(time.time()))
    # 第一次MD5
    md5_app_secret = hashlib.md5(APP_SECRET.encode()).hexdigest()
    # 拼接并第二次MD5
    sign_str = md5_app_secret + ts
    sign = hashlib.md5(sign_str.encode()).hexdigest()
    
    # 3. 构造请求
    url = f"https://api.thingboot.com/{APP_ID}/device/control/?sign={sign}&ts={ts}"
    
    # 4. 构造命令 (这就是你的"自定义模板")
    # 这里支持传入变量 text，实现了动态播报
    payload = {
        "device": DEVICE_ID,
        "order": {
            "play:gbk:16": text,   # 你要说的话
            "volume": volume,       # 音量
            "voice": voice,         # 音色 0=女 1=男
            "speed": speed         # 语速
        }
    }
    
    headers = {'Content-Type': 'application/json'}
    
    # 5. 发送请求
    try:
        response = requests.post(url, headers=headers, data=json.dumps(payload))
        print(f"状态码: {response.status_code}")
        print(f"响应内容: {response.text}")
        # 如果返回成功，音箱会在 100ms 左右响起来
        return response.json()
    except Exception as e:
        print(f"发送失败: {e}")
        return None

# 6. 调用示例:实现自定义模板
if __name__ == "__main__":
    # 场景1:会议提醒
    send_voice_message("张经理，三楼的客户已经等了五分钟了，请尽快返回会议室。", volume=7)
    
    # 场景2:设备告警（可以拼接变量）
    temp = 85
    send_voice_message(f"警告，机房温度已达{temp}度，请立即检查空调系统。", volume=9, voice=1)

总结与提示

网络环境：这款音箱走的是 2.4G WiFi，不支持 5G，配网时注意这一点。
签名时效：时间戳 ts 一般是秒级，签名通常有时间窗口校验（比如 5 分钟内有效），记得保证服务器时间是准确的。
字符编码：发送中文完全没问题，接口内部处理得很好，不需要转码。
私有化部署：如果你是在内网使用，这款产品也支持私有化部署，可以把 API 地址指向你自己的服务器。

通过这种方式，你可以把任何系统里的文本——不管是从数据库读的、从传感器采集的，还是 AI 生成的内容——实时转换成这 20W 音箱里的声音。