广场语音通知中：怎样把智能语音音柱|20W对接到自己的项目中_解决方案

CATALOG

这是一个把芯步20W智能语音音柱对接到你自己项目的实战指南。

我们会跳过复杂的硬件知识，直接聚焦在“怎么调通接口让它开口说话”上。为了方便理解，我会用比较直白的方式来写。

第一部分：拿到开启“金嗓子”的钥匙

在对代码动手之前，我们需要先去芯步的开放平台拿到两样东西，这就好比你要发微博，得先有个账号密码一样。

注册/登录：先去注册个账号。
创建应用：登录后，在控制台里找到“开发者设置”或“我的应用”，创建一个新应用。创建成功后，你会看到两个关键字符串：
- AppID：相当于你的“账号名”，告诉服务器是谁在请求。
- AppSecret：相当于你的“密码”，千万注意，这个东西别直接写在网页代码里，否则容易被别人看见拿去乱发广告。
拿到设备ID：把你手里的智能语音音柱|20W（也叫吸顶音箱）绑定到平台后，在设备列表里能看到一长串数字，那就是设备ID。可以把它想象成这台音箱的“身份证号”。

第二部分：核心秘籍——让音箱开口说话的“咒语”

芯步的接口设计得挺友好的，不用搞什么复杂的WebSocket连接，只要你服务器能发HTTP请求，就能让它响。

我们需要向这个地址发请求：

1. 必须搞懂的“签名”机制

为了防止接口被别人恶意调用，这里有一个签名（Sign） 的步骤。听着复杂，其实就是下面这个公式：

签名 = MD5 ( MD5(AppSecret) + 当前时间戳 )

别慌！ 翻译成人话就是：

先把你的“密码（AppSecret）”进行一次MD5加密。
把刚才得到的结果，再拼接上当前的“时间戳”（比如 1734567890）。
把拼好的这个大字符串，再进行一次MD5加密，最后得到的乱码就是签名。

这样做的好处是，每一次请求的签名都不一样，而且有时间限制，防止别人拿着你的链接到处刷。

2. 请求体怎么写？

我们需要通过 POST 方式，发送一个 JSON 格式的内容。

device：传你刚才查到的那个设备ID。
order：这是核心！对于20W音柱，命令格式是：{"play:gbk:16":"要播放的文字"}。

等等，为什么是 play:gbk:16？简单说一下：

play：就是让它播放。
gbk：是文字编码格式，一般中文用这个就行。
16这个很重要，是音量！范围一般是0到20。如果你发现音柱声音小得像蚊子叫，检查一下是不是这里写成了1或者2。

第三部分：实战代码演练

下面我用两段最常见的后端代码来演示。你可以直接复制过去，替换成自己的信息就能跑起来（注意：AppSecret不要暴露在前端）。

第一种场景：你用Python（比如Django/Flask后端）

如果你用的是Python，用 requests 库会非常简单。

import hashlib
import time
import requests
import json

# 1. 准备参数 (换成你自己的)
APP_ID = "你的AppID"
APP_SECRET = "你的AppSecret"
DEVICE_ID = "你的设备ID"

# 2. 你要说的话 (支持中文和数字)
text_to_speak = "你好，22号桌的客人，你的烤串已经烤好了，请来取餐。"

# 3. 计算签名
ts = int(time.time())
# 第一次MD5密码
md5_app_secret = hashlib.md5(APP_SECRET.encode()).hexdigest()
# 拼接后再MD5
sign_str = md5_app_secret + str(ts)
sign = hashlib.md5(sign_str.encode()).hexdigest()

# 4. 拼接URL
url = f"https://api.thingboot.com/{APP_ID}/device/control/"

# 5. 构造Body
# 注意:音量设为了16，你也可以调成18或20试试
payload = {
    "device": DEVICE_ID,
    "order": {f"play:gbk:16": text_to_speak}  # 稍微调整一下写法，确保转成字符串
}

# 修正order的格式，根据文档，order是一个JSON字符串或对象，这里requests库会自动处理dict，但为了保险，我们直接构造符合规则的dict
# 实际上 芯步的order字段直接传 {"play:gbk:16": "内容"} 即可
payload["order"] = {f"play:gbk:16": text_to_speak}

# 6. 发起请求
params = {
    "sign": sign,
    "ts": ts
}

headers = {
    "Content-Type": "application/json"
}

response = requests.post(url, params=params, headers=headers, data=json.dumps(payload))

print("状态码:", response.status_code)
print("返回内容:", response.text)

第二种场景：你用Go语言

如果你是用Go语言，逻辑完全一样。

package main

import (
	"bytes"
	"crypto/md5"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
	"strconv"
	"time"
)

func main() {
	AppID := "你的AppID"
	AppSecret := "你的AppSecret"
	DeviceID := "你的设备ID"

// 1. 准备文本
	text := "消防通道，请勿占用，请立即离开。"

// 2. 签名
	ts := time.Now().Unix()
	// md5(AppSecret)
	hash1 := md5.Sum([]byte(AppSecret))
	hash1Str := hex.EncodeToString(hash1[:])
	// md5(hash1 + ts)
	hash2 := md5.Sum([]byte(hash1Str + strconv.FormatInt(ts, 10)))
	sign := hex.EncodeToString(hash2[:])

// 3. 构造URL
	url := fmt.Sprintf("https://api.thingboot.com/%s/device/control/?sign=%s&ts=%d", AppID, sign, ts)

// 4. 构造Body
	orderCmd := map[string]string{"play:gbk:16": text}
	requestBody := map[string]interface{}{
		"device": DeviceID,
		"order":  orderCmd,
	}
	jsonData, _ := json.Marshal(requestBody)

// 5. 发送请求
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	req.Header.Set("Content-Type", "application/json")

client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println("请求失败:", err)
		return
	}
	defer resp.Body.Close()

body, _ := ioutil.ReadAll(resp.Body)
	fmt.Println("响应:", string(body))
}

第四部分：高级玩法——不止是广播

既然接口接好了，别只当个大喇叭用，可以玩点花活：

动态音量和语速：有时候晚上怕吵到人，或者白天需要更大声，你可以随时调。除了 play，你还可以下发命令调整这些参数，不用去现场拧按钮
- {"volume": 15} （调节音量）
- {"speed": 5} （调节语速）
特殊场景预警
- 食堂/餐厅：检测到用户在小程序下单，后端自动调用这个接口，喊一声“13号顾客请取餐”，连人工叫号都省了。
- 工厂/车间：对接你们的MES系统，哪个工位按了求助按钮，或者机器故障，音柱直接报“三号生产线请注意，物料即将耗尽”。
- 停车场：摄像头识别到车牌，你的软件系统直接通过音柱播报“京N12345，欢迎光临，请停放在A区”。

第五部分：排坑指南

如果你照着做了，但音箱不响，99%是以下三个原因：

签名不对（最常见）
- 检查一下时间戳（ts）是不是服务器当前时间？有的服务器时区不对也不行。
- 检查一下MD5的顺序：是 MD5(AppSecret) + ts，不是 AppSecret + ts。
网络问题
- 检查一下音柱的WiFi密码是不是输对了？在芯步的App里看设备状态是不是“在线”？如果是离线状态，喊破喉咙它也听不见。
音量问题
- 如果你发了命令但感觉没声音，看看是不是 play:gbk: 后面的数字写成了 1？改成 16 或 20 试试。

希望这份指南能帮到你。把这套逻辑写好封装成一个函数后，以后你在任何项目中想发个语音通知，调用一下这个函数就行了，非常方便。