共享茶室前台语音接待场景：如何将20W API 接口语音音柱接入到自己的项目中_解决方案

CATALOG

芯步的20W语音音柱通过HTTP接口就能直接控制，核心就是发送一个带签名的POST请求，把要播报的文字塞进order参数里。下面整理了从硬件准备到代码实现的完整接入流程。

一、硬件与准备：你手上的“万能钥匙”

首先，你得确保手里有这几样东西，缺一不可：

一台芯步 20W 语音音柱：这是主角，确保它通电并且连接了WiFi（或者插了网线）。
AppID 和 AppSecret：登录[芯步开放平台]，在控制台的“开发设置”里可以找到这两串字符。这相当于你项目的“用户名”和“密码”，调用接口全靠它们鉴权。
设备ID：在平台控制台的设备列表里，找到你那台音柱的一串数字ID。也就是你要指挥的“具体对象”。

二、核心技术：其实就两步

说白了，就是你的服务器 ——> 芯步云 ——> 音柱。

你不需要关心音柱底层的协议，只需要对着芯步的云服务器发个HTTP请求，服务器就会帮你去指挥音柱。

这里面唯一有点绕的是 “签名” ，不过按着公式来也很简单。

核心命令：如何让音柱开口说话

当你需要音柱说“你好”的时候，其实就是发送一个HTTP POST请求，内容如下：

请求地址https://api.thingboot.com/{你的AppID}/device/control/?sign={签名}&ts={时间戳}
请求方法：POST
请求体 (Body)
{ "device": "这里填你的设备ID", "order": {"play:gbk:16":"你好，欢迎光临"} }

注意看上面那个order参数，{"play:gbk:16":"你要说的话"}就是播放指令。里面的gbk代表文本编码，16代表音量（一般是0-15或0-100，具体看你设备文档，16算中等）。

关于鉴权（签名计算）

芯步为了安全，要求每一次请求都要带一个动态的sign。你可能会觉得这很麻烦，但其实只要把下面的逻辑封装成一个函数，以后就不用操心了。

计算步骤：

准备：AppSecret （原始密码）
Step 1：secret_md5 = md5(AppSecret)
Step 2：把 Step1的结果拼接上当前的ts（10位时间戳），得到 tmp = secret_md5 + ts
Step 3：sign = md5(tmp)

举例（伪代码逻辑）：

假设 AppSecret = "abc123"
Step1 结果：e99a18c428cb38d5f260853678922e03
当前 ts = 1712345678
Step2 拼接：e99a18c428cb38d5f260853678922e031712345678
Step3 最终的 sign = md5(上面的长串)

三、实战接入：Python 示例代码

为了让后端同学看起来更直观，我们直接上代码。这里用Python为例，其他语言（Java/Go/PHP）逻辑完全一样。

import hashlib
import time
import requests
import json

# 1. 配置你的三要素 (记得换成你自己的)
APP_ID = "你的AppID"
APP_SECRET = "你的AppSecret"
DEVICE_ID = "你的音柱设备ID"

def generate_sign_and_ts(secret):
    """生成时间戳和签名"""
    ts = str(int(time.time()))  # 获取当前时间戳（秒）
    # step1: md5(secret)
    step1 = hashlib.md5(secret.encode()).hexdigest()
    # step2: step1 + ts
    step2 = step1 + ts
    # step3: md5(step2)
    sign = hashlib.md5(step2.encode()).hexdigest()
    return ts, sign

def voice_broadcast(text):
    """让音柱说话"""
    # 接口地址
    url = f"https://api.thingboot.com/{APP_ID}/device/control/"
    
    # 获取签名和时间戳
    ts, sign = generate_sign_and_ts(APP_SECRET)
    
    # 拼接参数
    params = {
        "sign": sign,
        "ts": ts
    }
    
    # 拼接Body
    # 特别注意:这里假设你的设备指令是play:gbk:16，部分设备可能是 play=文本
    # 请根据芯步后台设备的产品详情确认指令格式
    payload = {
        "device": DEVICE_ID,
        "order": {"play:gbk:16": text}  # 如果是音量可调，改成比如{"play:gbk:50": text}
    }
    
    headers = {
        'Content-Type': 'application/json'
    }
    
    try:
        response = requests.post(url, params=params, data=json.dumps(payload), headers=headers)
        result = response.json()
        if result.get('code') == 200:
            print(f"播报成功:{text}")
        else:
            print(f"播报失败，错误码:{result.get('code')}")
    except Exception as e:
        print(f"接口调用异常:{e}")

# 测试一下
if __name__ == "__main__":
    voice_broadcast("您好，欢迎光临共享茶室，请出示您的预约码")

四、共享茶室语音场景具体落地

当硬件和代码逻辑通了之后，我们回到“共享茶室”的具体业务中。你需要把上面的API调用嵌入到以下业务逻辑里：

1. 客人进门时 (人来了)

当客人通过小程序/二维码扫开门的瞬间，后台系统接收到“门锁已开”的回调，立刻触发上面的voice_broadcast函数。

播报内容：“[温馨版] 欢迎光临，您的3号包间已准备好，祝您品茶愉快。”
进阶技巧：如果名字传给了接口，还可以试试支持多音字的TTS：“欢迎[具体会员名]贵宾光临。”

2. 超时提醒 (人要走了)

共享茶室通常是按小时计费。在订单即将结束前5分钟，后台定时任务查出哪个包间快超时了，调用音柱接口。

播报内容：“[提醒版] 3号包间，您的订单剩余时间仅剩5分钟，如需续费请扫码操作。”
避坑指南：不要把音柱放在包间里！共享茶室一般把音柱放在走廊天花板上。因为包间内客人在聊天喝茶可能听不见，放在走廊公共区域，客人出来上厕所或路过时能听到提醒，既不打扰隐私又能传达信息。

3. 呼叫服务员 (人喊人)

很多共享茶室是无人值守的，但客人万一要个纸巾呢？你可以在每个茶桌上放个无线按钮（或者小程序一键呼叫），当按下按钮，后台接收到指令，控制离这个包间最近的走廊音柱喊话：

播报内容：“服务员，请到3号包间。”

五、几个让你少走弯路的“小贴士”

关于音量：20W的音柱声音非常大，在室内走廊用，音量（上面的16）最好调小一点，比如10，否则会吓到客人。
关于网络：音柱是通过WiFi连接的，在信号好的地方安装。如果是地下室的茶室，记得用2.4G频段（穿墙好一点），5G可能连不上。
关于返回码：调用接口返回200只代表命令下发成功，不代表音箱响了。如果音箱没动静，先检查音箱控制台的设备状态是否在线，不在线的话就重新配网。
文本格式play:gbk:16 里的 gbk 表示中文字符编码，如果你播报英文或特殊数字，有时候用unicode或者不加编码直接play也行，具体看你的设备产品参数页最准。

通过这种方式，你的共享茶室前台甚至不需要坐人，只需要一个音柱和一行代码，就能实现全自动的智能迎宾和提醒服务。