怎么接入感应壁挂式语音终端以实现HTTP 接口文本推送_解决方案

CATALOG

芯步的感应壁挂式语音终端采用“HTTP接口推送文本，设备端合成语音”的方案——你只需要调用一个API，把文字发过去，设备就会自动播放。整个过程不需要上传录音，也不需要后台配置，核心就是发一条POST请求。

一、接入前的准备

在开始编程对接前，你需要准备三个关键信息，这些信息可以在芯步控制台的“开发设置”中找到

AppID (应用ID)：设备的应用唯一标识。
AppSecret (开发者密码)：用于接口签名加密的密钥，请注意保密。
Device ID (设备ID)：设备的唯一标识。即壁挂音箱的ID，也可以在控制台设备列表中查看。

此外，请确保设备已经通过2.4G Wi-Fi成功联网，并且指示灯状态正常。

二、接口协议与鉴权

感应壁挂式音箱使用的是统一的设备控制接口。该接口采用HTTP POST请求，数据格式为JSON，并且携带签名防止篡改。

1. 请求地址

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

{AppID}：替换为你实际的AppID。
{ts}：当前Unix时间戳（秒），必须是10位数字。
{sign}：请求签名，用于验证身份有效性。

2. 签名算法

签名生成规则为双重MD5加密，具体步骤如下

将 AppSecret 进行一次MD5加密，得到 encoded_secretencoded_secret = md5(AppSecret)
将上述结果与时间戳拼接，再进行一次MD5加密：sign = md5(encoded_secret + ts)

公式示意：

sign = md5( md5(你的开发者密码) + 时间戳 )

3. 请求头

Content-Type: application/json

三、核心：如何推送文本进行播报

要实现“文本推送语音播报”，最关键的是 order 参数。在请求的Body中，你需要构造一个JSON对象，包含 device 和 order。

对于壁挂音箱，播报命令的格式如下

play:gbk:16 表示这是一个播报指令，支持中英文混合文本。

四、代码示例

以下是如何调用接口让音箱播报“你好，欢迎光临”的示例：

示例 1：使用 Shell (cURL)

这种方法适合在Linux服务器上通过脚本快速测试。

示例 2：使用 Java

适合集成到现有的Java后端服务中（需要使用Unirest或OkHttp库）。

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

public class YoyoVoiceTest {
    public static void main(String[] args) {
        String AppID = "你的AppID";
        String AppSecret = "你的AppSecret";
        String DeviceID = "你的设备ID";
        long ts = System.currentTimeMillis() / 1000;
        
        // 计算签名
        String md5Secret = DigestUtils.md5Hex(AppSecret);
        String sign = DigestUtils.md5Hex(md5Secret + ts);
        
        String url = String.format("https://api.thingboot.com/%s/device/control/?sign=%s&ts=%d", 
                                    AppID, sign, ts);
        
        // 构造命令
        String orderJson = "{\"play:gbk:16\":\"你好，欢迎光临\"}";
        String body = String.format("{\"device\":\"%s\",\"order\":%s}", DeviceID, orderJson);

try {
            HttpResponse<String> response = Unirest.post(url)
                .header("Content-Type", "application/json")
                .body(body)
                .asString();
            System.out.println(response.getBody());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

五、高级功能：让你的播报更自然

除了简单文本，感应壁挂音箱还支持通过 order 命令控制音量和音色，甚至优化数字读法。

1. 控制音量和音色

在推送文本之前或同时，可以下发音量设置命令，支持0-9级。

2. 多命令组合

虽然设备通常接收一个 order 对象，但你可以先设置音量/音色，再设置播报。或者在播报文本中加入数字读法标识来优化播报效果。

数字优化：接口会自动识别数字，但你可以通过标记指定读法。
- [n2]1888：金额读法（一千八百八十八）
- [n3]13800138000：手机号读法（一三八...）
多音字：使用 [=x] 标记指定读音。
- 请把空调调[=tiao2]高一点

带高级格式的播报示例：

六、常见问题与错误码

如果接口调用失败，请根据下表排查

错误码 (code)	原因	解决方案
5001	缺少 App ID	检查URL路径中是否包含正确的AppID。
5003	时间戳错误	检查服务器时间是否为标准北京时间，时间戳是否为秒级（10位）。
5006	签名错误	检查签名算法，特别是MD5后的字符串拼接顺序是否正确。
5009	请求过于频繁	单个设备请求频率限制为1次/秒，请注意控制频率，避免设备持续繁忙。

通过以上步骤，你可以在30分钟内完成感应壁挂式语音终端的HTTP接口对接，实现从业务系统到硬件终端的实时语音播报。