py-tjbrhk-toolkit

介绍

天津博瑞皓科博瑞云音箱 Python 客户端库，实现官方《博瑞云音箱 API 对接文档》中定义的全部接口。

py-tjbrhk-toolkit 是天津博瑞皓科博瑞云音箱 API 的 Python 客户端库。它严格基于 官方文档（语雀） 实现，覆盖以下全部接口：

接口约定（来自官方文档）：

• 所有接口均为 POST 请求，以 application/x-www-form-urlencoded 提交表单数据。
• 返回 JSON 格式 {"errcode", "errmsg", "detail"}，errcode 为 0 即视为业务成功。
• 本库不涉及登录与 Token 缓存，Token 由调用方自行管理并传入。

软件架构

py_tjbrhk_toolkit/
├── pyproject.toml
├── README.md
├── README.en.md
├── LICENSE
├── src/
│   └── py_tjbrhk_toolkit/
│       ├── __init__.py
│       ├── py.typed
│       └── speaker/
│           ├── __init__.py
│           ├── client.py     # SpeakerClient（同步）与 AsyncSpeakerClient（异步）
│           └── models.py     # Pydantic 响应模型
├── tests/
│   └── speaker/
│       ├── __init__.py
│       ├── conftest.py
│       ├── test_speaker_sync.py
│       └── test_speaker_async.py
└── examples/
    └── speaker/
        ├── __init__.py
        ├── .env.example
        ├── example_common.py
        ├── example_notify.py
        ├── example_bind.py
        ├── example_add.py
        ├── example_modify_boot_voice_wav.py
        ├── example_async_notify.py
        ├── example_async_bind.py
        ├── example_async_add.py
        └── example_async_modify_boot_voice_wav.py

安装教程

推荐使用 uv 安装：

uv add py-tjbrhk-toolkit

或使用 pip 安装：

pip install py-tjbrhk-toolkit

从本地源码安装（开发模式）：

uv venv .venv
source .venv/bin/activate
uv pip install -e .
uv pip install -e ".[dev]"

使用说明

from py_tjbrhk_toolkit.speaker.client import SpeakerClient

client = SpeakerClient(
    base_url="https://speaker.17laimai.cn/",
    token="your_token",
    id="your_speaker_id",
    version="1",
)

# 通知语音播报（流量版专用）
response = client.notify(message="[123]收款66元", vol=80)
print(response.json())

# 云音箱绑定（m=1 绑定，0 解绑，4 强制解绑）
response = client.bind(m=1, uid="user_123")

# 支付语音播报（price 单位为分）
response = client.add(price="3879", pt=1, vol=80)

# 更改语音信息（灰度测试，仅 402/404/502/504）
response = client.modify_boot_voice_wav(sound="欢迎光临", type=0, off_text="谢谢使用")

client.close()

异步模式：

import asyncio
from py_tjbrhk_toolkit.speaker.client import AsyncSpeakerClient


async def main():
    client = AsyncSpeakerClient(
        base_url="https://speaker.17laimai.cn/",
        token="your_token",
        id="your_speaker_id",
        version="1",
    )
    response = await client.async_notify(message="Hello World")
    print(response.json())
    await client.close()


asyncio.run(main())

所有客户端均支持 with / async with 上下文管理器，退出时自动关闭底层 httpx 客户端。

参与贡献

欢迎提交 Issue 和 Pull Request。在提交 PR 之前，请先运行测试并确保代码符合项目规范。

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

uv pip install -e ".[dev]"
pytest

特技

1. 基于 httpx 与 pydantic，提供同步（SpeakerClient）与异步（AsyncSpeakerClient）两种客户端。
2. 严格基于官方 API 文档实现全部接口，支持 with / async with 上下文管理器，退出时自动关闭底层客户端。
3. 提供中英文双语 README（README.md / README.en.md）。
4. 采用 MIT 开源许可协议。