怎样接入10W 远程控制 TTS 语音音柱来实现HTTP接口文本推送_解决方案

CATALOG

10W远程控制TTS语音音柱的核心价值在于“文本即播报”——无需预先录音，直接通过HTTP接口推送文本即可实时合成语音，可无缝接入各类订单提醒、告警通知、流程语音引导等业务场景。

以下是基于芯步开放接口的完整接入方案。

1. 接入前准备

在开始编码前，需要在芯步控制台完成以下准备工作：

注册与创建应用：登录芯步官网，注册账号并创建一个工作台（即应用）。系统会自动生成唯一的 AppID（应用标识）和 AppSecret（应用密钥），这对信息后续用于接口鉴权。
设备配网与ID获取：将10W语音音柱通电，按照控制台或小程序的指引为其配置WiFi（仅支持2.4GHz）。配网成功后，在控制台的设备列表中查看并复制该音柱的 Device ID（设备唯一ID），后续接口调用需要用到。
确认指令格式：TTS音柱通过 order 参数中的特定JSON字段接收文本。根据资料，播报指令格式为 {"play:gbk:16":"要播报的文字内容"}。

2. 接口鉴权与请求详解

芯步的开放API采用动态签名的方式保障接口安全。

2.1 签名算法

每一个API请求都需要携带 sign（签名）和 ts（时间戳）参数，服务端会校验两者的合法性与时效性。

签名生成步骤：

对 AppSecret 进行一次MD5加密，得到字符串 S1。
将 S1 与当前的时间戳 ts（Unix时间戳，单位秒）直接拼接，得到字符串 S2。
对 S2 进行一次MD5加密，得到最终的 sign。

计算公式：S1 = md5(AppSecret)S2 = S1 + tssign = md5(S2)

示例：假设 AppSecret = “abc123”，当前ts = 1747212640。

S1 = md5(“abc123”) = e99a18c428cb38d5f260853678922e03
S2 = “e99a18c428cb38d5f260853678922e03” + “1747212640”
sign = md5(S2) = c484eb97ee288572db7828c6071dd88f

2.2 请求地址与头信息

请求地址https://api.thingboot.com/{AppID}/device/control/
请求方式：POST
参数位置sign 和 ts 放在URL Query参数中；device 和 order 放在Body中（推荐JSON格式）。
Content-Typeapplication/json

3. 核心代码实现（HTTP文本推送）

以下是两种最常用的对接方式，您只需将代码中的 AppID、AppSecret、DeviceID 和 Text 替换为您自己的数据即可运行。

3.1 Python 实现（通用后端）

适用于Django、Flask等后端服务，或脚本任务。

import requests
import hashlib
import time
import json

# 配置信息
APP_ID = "你的AppID"
APP_SECRET = "你的AppSecret"
DEVICE_ID = "你的设备ID"  # 从控制台获取

def yoyo_tts_control(text_to_say):
    # 1. 准备时间戳和签名
    ts = str(int(time.time()))
    s1 = hashlib.md5(APP_SECRET.encode()).hexdigest()
    s2 = s1 + ts
    sign = hashlib.md5(s2.encode()).hexdigest()

# 2. 构建URL
    url = f"https://api.thingboot.com/{APP_ID}/device/control/？sign={sign}&ts={ts}"

# 3. 构建Body
    # 注意TTS指令格式: {"play:gbk:16":"你要说的话"}
    payload = {
        "device": DEVICE_ID，
        "order": {"play:gbk:16": text_to_say}
    }

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

# 5. 处理返回
    if response.status_code == 200:
        res_json = response.json()
        if res_json.get("code") == 200:
            print("指令下发成功，音柱准备播报 ")
        else:
            print(f"下发失败: {res_json}")
    else:
        print("HTTP请求失败")

if __name__ == "__main__":
    yoyo_tts_control("你好，仓库内有新订单，请及时处理。")

3.2 Java (Spring Boot) 实现

适用于企业级Java应用程序。

import org.springframework.http.*;
import org.springframework.web.client.RestTemplate;
import org.springframework.util.LinkedMultiValueMap；
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException；

public class YoyoTTSService {
    private static final String APP_ID = "你的AppID";
    private static final String APP_SECRET = "你的AppSecret"；
    private static final String DEVICE_ID = "你的设备ID"；

public static void sendTTSCommand(String text) throws NoSuchAlgorithmException {
        // 1. 生成签名
        long ts = System.currentTimeMillis() / 1000;
        String s1 = md5(APP_SECRET);
        String s2 = s1 + ts;
        String sign = md5(s2);

// 2. 构建URL
        String url = "https://api.thingboot.com/" + APP_ID + "/device/control/？sign=" + sign + "&ts=" + ts;

// 3. 构建Body
        RestTemplate restTemplate = new RestTemplate（）；
        HttpHeaders headers = new HttpHeaders（）；
        headers.setContentType(MediaType.APPLICATION_JSON);

// 构造JSON参数
        String jsonBody = String.format("{\""device\"":\""%s\""，\""order\"":{\""play:gbk:16\"":\""%s\""}}"， DEVICE_ID, text);

HttpEntity<String> entity = new HttpEntity<>(jsonBody, headers);

// 4. 发送请求
        ResponseEntity<String> response = restTemplate.postForEntity(url, entity, String.class);

System.out.println("返回结果: " + response.getBody（））；
    }

// MD5工具方法
    private static String md5(String input) throws NoSuchAlgorithmException {
        MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] digest = md.digest(input.getBytes（））；
        StringBuilder sb = new StringBuilder();
        for (byte b : digest) {
            sb.append(String.format("x"， b & 0xff));
        }
        return sb.toString();
    }
}

4. 进阶指令与场景配置

除了基础的文本播报，10W音柱还支持一系列控制指令，您可以通过修改 order 参数实现更丰富的体验。

4.1 播报控制指令表

| 功能说明 | Order 参数格式（JSON） | 示例值 | 适用场景 || ：--- | ：--- | ：--- | ：--- || TTS文本播报 | {“play：gbk：16”：“文本”} | {“play：gbk：16”：“2048号，请到3号窗口”} | 排队叫号、工单提醒 || 调节音量 | {“volume”：数值} | {“volume”：80} | 白天/夜间音量自适应（范围0-100） || 切换音色 | {“voice”：数值} | {“voice”：1} | 区分紧急通知（男声）与普通通知（女声） || 播放内置铃声 | {“ring”：数值} | {“ring”：1} | 紧急情况告警 || 停止当前播报 | {“stop”：1} | {“stop”：1} | 强制打断，播放更高优先级内容 |

4.2 并发与广播场景

单个请求控制多台设备：如果您的场地有多个音柱需要同时播报，可以在 device 参数中用英文逗号 ， 连接多个设备ID。
- “device”： “123456,789012,345678”
- 注意：所有被指定的设备必须支持相同的 order 指令。
携带业务扩展信息：可以在命令中添加 extra 字段，用于关联内部订单号。设备执行结果异步推送时，会原样返回此字段。
- {“play：gbk：16”：“新订单”， “extra”：“ORDER_2023001”}

5. 注意事项

异步反馈/device/control/ 接口返回 200 仅代表指令成功下发给云端，不代表设备已成功播报。对于必须确保播报成功的场景，配置消息推送（接收设备回执）。
文本编码：确保POST请求的编码为UTF-8。中文字符不需要额外转换，直接传入JSON字符串即可。
网络要求：设备仅支持2.4G WiFi，请确保现场WiFi信号覆盖良好，避免因网络延迟导致播报不及时。

6. 总结

通过以上步骤，您已经完成了从环境准备、签名鉴权到代码集成的全部流程。芯步10W音柱的开放接口设计非常直观——核心逻辑即 “通过HTTP POST携带签名+设备ID+TTS文本到指定URL”。

对于开发者而言，只需要关注业务逻辑中 “何时触发播报” 以及 “播报什么内容”。可以将上述代码封装成一个独立的 VoiceService 工具类，在订单创建成功、设备异常告警、或传感器触发等业务节点直接调用即可。