如何二次开发10W HTTP 接口语音音柱来实现远程TTS语音播报_解决方案

CATALOG

芯步的10W语音音柱支持通过HTTP接口直接推送文本进行TTS播报，无需预先录音，响应延迟约80-120ms。以下方案涵盖接口协议、签名算法、核心命令及多第二种场景次开发示例。

一、概述与准备

本方案的目标是指导开发者如何利用芯步开放的HTTP API，将10W智能语音音柱快速集成到现有的业务系统（如ERP、餐厅系统、工单系统等）中。通过调用API接口，实现将文本消息实时转换为语音并在指定音柱上播报。

准备工作：

硬件设备：芯步10W智能语音音柱（确保已连接WiFi/网口并通电）。
平台账号：在芯步官网注册开发者账号，登录控制台。
获取凭证：在控制台获取AppID和AppSecret（开发者密码）以及设备的Device ID（设备唯一ID）。

二、接口协议详解

芯步的接口采用标准的HTTP POST请求进行通信，数据格式为JSON。核心逻辑是签名验证，确保请求安全。

1. 请求地址

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

{AppID}：你的应用ID。
{ts}：当前Unix时间戳（秒）。
{sign}：请求签名，用于身份验证。

2. 签名算法

这是对接的关键步骤，具体算法逻辑如下：

将你的 AppSecret 进行一次MD5加密，得到字符串 S1。
将 S1 拼接上时间戳 ts（注意是拼接字符串）。
将拼接后的字符串再次进行MD5加密，得到最终的 sign。

公式：

sign = md5( md5(AppSecret) + ts )

示例：假设 AppSecret = "123456"，ts = 1747212640。

md5("123456") -> e10adc3949ba59abbe56e057f20f883e
拼接 -> e10adc3949ba59abbe56e057f20f883e1747212640
md5(拼接字符串) -> c484eb97ee288572db7828c6071dd88f (这就是sign值)。

3. 请求体 (Body)

请求头需设置 Content-Type: application/json。Body结构如下：

device：支持字符串格式，可传单个ID（如 "1878"）或多个ID（如 "1878,1879"）。
order：JSON对象，此处填写具体的控制指令。

三、核心功能实现：TTS语音播报

根据需求，“远程TTS语音播报”主要使用 play:gbk:16 命令。此命令支持GBK编码（中文支持良好），数字16通常代表默认的音质或格式。

1. 基础文本播报

最简单的应用，直接推送文字内容。

请求示例
{ "device": "820720", "order": {"play:gbk:16": "你好，欢迎光临"} }
效果：音柱会立即播报“你好，欢迎光临”。

2. 高级播报格式（带提示音/多音字/数字读法）

你可以通过在文本前插入特定的标签来控制播报行为。

带提示音播报
{"order": {"play:gbk:16": "[message_1]您有新的订单，请及时处理"}}
(注：message_1 到 message_5 为内置提示音，ring_1 到 ring_5 为铃声)。
控制数字读法
- 金额读法：自动识别为“一百二十三元”。
- 手机号读法：自动识别为“幺三八零零零...”。
多音字：某些生僻多音字可通过特定标记矫正，具体可参考官方文档。

3. 设备状态控制命令

在进行语音播报前或播报后，你可以动态调整设备参数。

调节音量： {"volume":"5"} (范围0-9，数值越大音量越大)。
切换音色： {"voice":"1"} (0=女声，1=男声)。
调节语速： {"speed":"5"} (范围0-9)。
停止播报： {"stop":"1"} (1=停止当前所有播报)。

四、二次开发代码实战

根据你的业务系统架构，可以选择以下任意一种方式集成。

第一种场景：Python (适用于后端服务、脚本)

第二种场景：Java (适用于企业级SpringBoot应用)

可以使用OkHttp或Unirest库。

import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.HttpResponse;
import org.apache.commons.codec.digest.DigestUtils;

public class YoyoVoiceDemo {
    public static void main(String[] args) {
        String appId = "你的AppID";
        String secret = "你的AppSecret";
        String deviceId = "你的设备ID";
        long ts = System.currentTimeMillis() / 1000L;
        
        // 计算签名
        String md5Secret = DigestUtils.md5Hex(secret);
        String signRaw = md5Secret + ts;
        String sign = DigestUtils.md5Hex(signRaw);
        
        // 构建命令
        String orderJson = "{\"play:gbk:16\":\"工单#00122已超时，请尽快处理\"}";
        
        try {
            HttpResponse<String> response = Unirest.post("https://api.thingboot.com/" + appId + "/device/control/")
                    .queryString("sign", sign)
                    .queryString("ts", ts)
                    .header("Content-Type", "application/json")
                    .body("{\"device\":\"" + deviceId + "\",\"order\":" + orderJson + "}")
                    .asString();
            System.out.println(response.getBody());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

第三种场景：JavaScript/Node.js (适用于Web前端或Serverless)

五、最佳实践和需要注意的点

局域网IP直连（可选）如果你的音柱和服务器在同一个局域网内，官方支持私有化部署或局域网调用。这种情况下可以绕过公网，延迟更低（可降低至50ms以内）且不占用外网带宽。具体获取设备局域网IP的方式请参考设备配网后的信息。
批量播报如果需要同时让多个音柱播报（如整个厂房的广播），只需要在 device 字段中用英文逗号拼接设备ID，例如 "device": "1878,1879,1880"。
播报队列硬件内部有播报队列。如果短时间内高频调用接口，后一条命令会排队等待前一条播完。如果希望新消息打断旧消息，可以先发送 {"stop":"1"} 命令，再发送播报命令。
错误处理请一定要在代码中捕获HTTP状态码非200的情况，并检查返回的JSON体中是否有 code 错误字段。常见错误是签名不正确（核对时间戳同步）或Device ID不在你的账号下。