怎样接入30W 云 TTS 语音音柱以实现自定义语音模板设置_解决方案

CATALOG

芯步30W音柱通过开放HTTP接口，支持动态TTS播报和自定义模板。以下方案涵盖签名计算、参数配置到代码实现的完整流程，你可根据业务场景直接调用。

解决方案：基于芯步开放接口接入30W TTS语音音柱并实现自定义语音模板设置

1. 解决概述

芯步智能语音音柱（含30W规格）提供了基于HTTP协议的开放接口。用户无需依赖复杂的私有SDK，只需通过标准的HTTP POST请求，即可向指定设备下发TTS（Text To Speech，文本转语音）指令。

为实现“自定义语音模板”的需求，核心思路是在您的业务系统（服务端）中维护一套动态模板引擎。将固定的通知格式与变量（如人名、金额、车牌号等）分离，通过代码动态拼接成符合要求的文本字符串，最终通过调用芯步的开放接口推送给音柱设备。

2. 接口对接前置准备

在开始开发前，请确保完成以下准备工作，获取必要的凭证：

注册账号：在芯步开放平台注册开发者账号。
获取凭证：登录控制台，在“开发设置”中获取 AppID 和 AppSecret（开发者密码）。这两个参数是后续生成接口签名的基础。
设备就绪：确保30W智能语音音柱已通电并成功连接至Wi-Fi（2.4GHz）或通过网口联网。在控制台设备列表中获取该音柱的唯一标识 Device ID。

3. 核心技术原理：签名计算

芯步接口采用动态签名验证机制，每一次请求都需要计算sign。算法规则如下

第一步：将 AppSecret 进行一次MD5加密，得到 encrypted_secret。
- encrypted_secret = MD5(AppSecret)
第二步：拼接字符串。将上一步得到的 encrypted_secret 与当前Unix时间戳 ts （精确到秒）进行拼接。
- string_to_sign = encrypted_secret + ts
第三步：生成最终签名。将拼接后的字符串再次进行MD5加密。
- sign = MD5(string_to_sign)

注意：时间戳 ts 需要作为参数与 sign 一同在URL中传递，且时间戳与服务器时间误差不宜过大，否则会因鉴权失败导致接口报错。

4. 自定义语音模板的设计

为了实现灵活的播报逻辑，在后端建立如下设计：

模板库：建立模板字典，例如 order_notify = “【新订单】您有一个新的{平台}订单，订单尾号{尾号}，请及时处理。”
变量替换逻辑：后端接收到业务触发信号时，从数据库提取真实的数据替换模板中的占位符（如{平台}、{尾号}）。
高级文本标签：芯步TTS引擎支持内置的SSML（语音合成标记语言）标签，可以在拼接文本时插入，以实现更自然的人机交互。
- 数字读法控制：金额添加 [money] 标签。
  - 示例“消费金额[money]99.9[/money]元”（读作“九十九点九元”，而非“九九点九”）。
- 多音字纠正：使用 [pron] 标签指定读音。
  - 示例“[pron]qian[/pron]江路”或“[pron]xing[/pron]宝路”（用于“行走”的“行”）。
- 停顿控制：在长文本中加入 [break] 实现断句。
  - 示例“倒车请注意[break]倒车请注意”。

5. 关键接口调用详解（HTTP API）

请求地址（POST方式）：https://api.thingboot.com/{AppID}/device/control/?sign={sign}&ts={ts}

请求头（Headers）

Content-Type: application/json

请求体（Body）参数

6. 针对30W音柱的进阶控制选项

在 order 对象中，除了 play：gbk：16 播报指令外，通常在播报前或播报时附带设备状态调整。以下是30W音柱支持的扩展参数，可用于实现更丰富的“模板”效果

功能分类	命令Key	取值范围/说明	场景示例
音量调节	`volume`	“0” ~ “9” (9为最大音量)	白天场景用高音量，夜晚场景自动调低音量
音色选择	`voice`	“0”(女声)， “1”(男声)	紧急警报用男声显得严肃，温馨提醒用女声
语速语调	`speed`/`tone`	“0” ~ “9” (5为标准)	播报长串数字时可适当调慢语速
前置提示音	`message`	“1”~“5” (内置5种不同提示音)	在语音播报前播放“叮咚”一声，吸引注意力
停止播报	`stop`	“0”(停止当前)，“1”(全部停止)	遇到更高级别的紧急事件时，立即打断当前低优先级播报

组合命令示例（包含音量+音色+内容）：

注：在一条请求中同时下发音量和播报命令，设备会按顺序执行，通常先调好音量再播报。

7. 实战代码示例（Python）

以下是一个完整的Python脚本示例，演示了如何实现自定义模板签名计算及设备调用。

import hashlib
import time
import json
import requests

# 1. 配置参数
APP_ID = "你的AppID"          # 替换为控制台获取的 AppID
APP_SECRET = "你的AppSecret"    # 替换为控制台获取的 AppSecret
DEVICE_ID = "你的30W音柱ID"     # 替换为设备列表中的 Device ID

# 2. 业务层:自定义模板逻辑
def generate_custom_message(order_info):
    """
    业务模板: 根据订单信息生成播报文本
    """
    # 假设判断为重要订单，需加提示音标签并处理金额读法
    amount_part = f"[money]{order_info['amount']}[/money]元"
    msg = f"【重要提醒】您有一个来自{order_info['platform']}的订单，金额{amount_part}，请尽快处理。"
    return msg

# 3. 接口层:构建请求
def send_voice_command(text_content):
    # 生成时间戳（秒级）
    ts = int(time.time())
    # 计算签名: md5(md5(secret) + ts)
    md5_secret = hashlib.md5(APP_SECRET.encode(‘utf-8’)).hexdigest()
    sign_str = md5_secret + str(ts)
    sign = hashlib.md5(sign_str.encode(‘utf-8’)).hexdigest()
    
    # 拼接 URL
    url = f"https://api.thingboot.com/{APP_ID}/device/control/？sign={sign}&ts={ts}"
    
    # 构建请求体 (这里设定音量为8，女声，并加提示音)
    payload = {
        "device": DEVICE_ID,
        "order": {
            "volume": "8",          # 音量 80%
            "voice": "0",          # 女声
            "play:gbk:16": text_content
        }
    }
    headers = {"Content-Type": "application/json"}
    
    # 发送请求
    response = requests.post(url, headers=headers, data=json.dumps(payload), timeout=5)
    return response.json()

# 4. 执行流程
if __name__ == "__main__":
    # 模拟业务数据
    order = {"amount": 99.9, "platform": "美团"}
    # 生成自定义语音文本
    tts_text = generate_custom_message(order)
    print(f"准备播报: {tts_text}")
    # 调用接口下发
    result = send_voice_command(tts_text)
    print(f"接口响应: {result}")

8. 高级应用：预定义模板ID与参数化

如果不想每次都传递长字符串，或者希望前端直接触发播报（避免后端过度封装），可以在您的后端做一个模板映射接口

注册模板：在后端数据库定义模板ID 1001，对应内容“欢迎[pron]xing[/pron]宝路，请出示健康码”。
简化调用：前端或第三方系统调用您的API：/api/voice/play？template_id=1001&name=张三。
后端逻辑：您的服务器接收到请求 -> 查询模板 -> 替换变量 name -> 拼接文本 -> 调用上述第7节中的 send_voice_command 函数。

通过这一层代理，实现了业务语义与物理硬件的彻底解耦，维护起来更加方便。

9. 总结

通过芯步的开放接口，开发者可以快速将30W TTS语音音柱集成到现有的业务系统中。关键在于：

正确实现 MD5-MD5 签名机制进行身份验证。
利用自有的 Service 层进行模板变量替换，生成符合业务场景的自然语言文本。
善用接口中的 音量、音色和内置提示音参数，提升用户体验。

该解决方案不仅支持公网SaaS模式，也支持私有化部署，运行在纯局域网环境中，保障数据安全。