怎么对接20W 云 TTS 语音壁挂音箱以实现HTTP 接口文本推送_解决方案

CATALOG

芯步20W云TTS语音壁挂音箱提供标准的HTTP API接口，文本推送的核心是将待播文本封装为JSON命令，通过携带签名认证的POST请求发送至设备控制接口。以下是完整的技术对接方案。

1. 核心对接原理

本方案采用HTTP协议 + 多重签名认证 + 文本直推的技术路径。

适用产品：芯步 20W 智能语音壁挂音箱（款式1/吸顶款）。
核心优势：无需预先上传录音或MP3文件，接口支持直接推送中文字符串，设备端接收后实时进行语音合成播报。
响应速度：从发起请求到音箱出声，通常在 80-120ms 内完成。

2. 准备工作：获取凭证与网络配置

在开始编码前，必须准备好以下三个关键要素：

获取 AppID 与 AppSecret登录芯步物联网控制台，进入“开发设置”页面。系统会为您的应用分配唯一的身份标识（AppID，字符串）和密钥（AppSecret，用于计算签名）。
获取设备 ID在控制台的设备列表中找到目标“20W云TTS语音壁挂音箱”，获取其唯一的 Device ID。该 ID 是下发命令时的必要参数。
确保网络连通该音箱采用 WiFi 2.4G 无线连接方式，无需网关。请确保在配网阶段已为音箱配置了可访问公网的WiFi网络（若为私有化部署则需指向私有API地址）。

3. 接口鉴权与指令集解析

3.1 签名计算规则

为了安全，所有API请求都需要进行动态签名验证。签名生成规则如下：

sign = \text{MD5}(\ \text{MD5}(AppSecret)\ \&\ ts\ )

参数说明

AppSecret：从控制台获取的密钥。
ts：当前的Unix时间戳（秒级），用于防止请求重放。
拼接：先将 AppSecret 进行一次 MD5 加密（得到32位小写字符串），再拼接上时间戳 ts，最后对这个新字符串再进行一次 MD5 加密。

3.2 关键控制指令 (JSON格式)

针对20W TTS语音音箱，HTTP请求中的 order 参数支持以下操作：

文本播报{"play:gbk:16":"这里输入要说的内容"}
- 格式解析play 为动作；gbk 为编码格式；16 代表音量（范围0-31，非必须，可忽略使用默认）。
- 示例{"play:gbk:16":"您有一条新的订单，请及时处理"}。
音量控制{"vol":80}
- 范围：0-100。
音色变换{"voice":"boy"} 或 {"voice":"girl"}
- 支持男女声切换。

4. 实战对接：HTTP接口调用示例

对接地址为： https://api.thingboot.com/{AppID}/device/control/

请求方式： POSTContent-Type： application/json

4.1 Bash (cURL) 示例

适用于Linux服务器脚本或简单的命令行测试。

4.2 Python 示例

适用于集成到现有的Python后端服务（如Flask/Django）。

import hashlib
import time
import requests
import json

def yoyo_tts_push(app_id, app_secret, device_id, text):
    # 1. 构建时间戳和签名
    ts = int(time.time())
    # 计算签名:md5(md5(secret) + ts)
    md5_secret = hashlib.md5(app_secret.encode()).hexdigest()
    sign_str = md5_secret + str(ts)
    sign = hashlib.md5(sign_str.encode()).hexdigest()
    
    # 2. 构建URL和Headers
    url = f"https://api.thingboot.com/{app_id}/device/control/"
    params = {
        "sign": sign,
        "ts": ts
    }
    headers = {
        "Content-Type": "application/json"
    }
    
    # 3. 构建Body
    payload = {
        "device": device_id,
        "order": {
            "play:gbk:16": text   # 文本播报命令
        }
    }
    
    # 4. 发送请求
    response = requests.post(url, params=params, headers=headers, json=payload)
    return response.json()

# 调用示例
if __name__ == "__main__":
    result = yoyo_tts_push(
        app_id="你的AppID",
        app_secret="你的AppSecret",
        device_id="设备ID",
        text="仓库货架A3发生火警，请立即处理"
    )
    print(result)

4.3 Java 示例

适用于企业级Spring Boot应用。

import okhttp3.*;
import java.io.IOException;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

public class YoyoTTSClient {
    public static void main(String[] args) throws Exception {
        String appId = "你的AppID";
        String appSecret = "你的AppSecret";
        String deviceId = "设备ID";
        
        long ts = System.currentTimeMillis() / 1000L;
        String sign = generateSign(appSecret, ts);
        
        OkHttpClient client = new OkHttpClient();
        
        String url = String.format("https://api.thingboot.com/%s/device/control/?sign=%s&ts=%d", appId, sign, ts);
        
        MediaType JSON = MediaType.parse("application/json; charset=utf-8");
        String jsonBody = String.format("{\"device\":\"%s\",\"order\":{\"play:gbk:16\":\"设备温度过高，请注意检查\"}}", deviceId);
        
        Request request = new Request.Builder()
                .url(url)
                .post(RequestBody.create(jsonBody, JSON))
                .build();
                
        Response response = client.newCall(request).execute();
        System.out.println(response.body().string());
    }
    
    private static String generateSign(String secret, long ts) throws NoSuchAlgorithmException {
        // MD5(secret)
        String md5Secret = md5(secret);
        // MD5(md5Secret + ts)
        return md5(md5Secret + ts);
    }
    
    private static String md5(String input) throws NoSuchAlgorithmException {
        MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] messageDigest = md.digest(input.getBytes());
        StringBuilder sb = new StringBuilder();
        for (byte b : messageDigest) sb.append(String.format("x", b));
        return sb.toString();
    }
}

5. 高级特性与优化

5.1 SSML与数字读法优化

20W音箱针对特定场景做了优化，直接传输文本即可智能处理以下格式

金额：传 “您收到了99.99元” → 会读作“九十九点九九元”。
手机号：传 “请联系13812345678” → 会读作“幺三八幺二三四五六七八”。
多音字：如果默认读法不对，在文本中通过同音字替换微调（如将“行走”改为“步行”）。

5.2 异步回调与状态监控

为了确认音箱确实播报了（而不仅仅是接口收到请求），您可以配置消息推送

音箱在执行命令后（如播报完毕、播报失败），会主动向您预设的服务器地址推送执行结果。
这可以帮助你建立任务队列，确认关键通知（如警报）是否送达。

5.3 批量与分组播报

多设备推送device 参数支持一次性传入多个ID，用英文逗号隔开。例如 device="ID1,ID2,ID3"，可实现办公室、仓库、车间同时播报。
私有化部署：若您的系统运行在纯内网环境（无公网IP），该系列音箱支持私有化部署。您可以将API地址指向自己的局域网服务器。

6. 常见问题排查

报错“Sign Error”
- 原因：时间戳（ts）误差过大或签名计算逻辑错误。
- 解决：确认服务器时间是否同步（误差最好在5分钟内）；检查 MD5 结果是否为 32位小写 十六进制字符串。
命令下发成功但音箱不响
- 原因：设备离线或音量命令设置冲突。
- 解决：检查音箱网络指示灯状态。可尝试在命令中增加 {"vol":80} 设置较高音量，且确保 {"power":1}（如果设备有独立开关机功能）。
中文乱码
- 解决：确保HTTP请求头明确指定了 Content-Type: application/json; charset=utf-8，且代码文件本身保存为UTF-8编码。

通过以上步骤，您可以快速完成20W云TTS语音壁挂音箱的HTTP接口对接，将文本语音通知能力集成到现有的ERP、餐饮系统或安防系统中。