py-tjbrhk-toolkit

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

关于

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

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

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

安装

推荐使用 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 客户端。

API 参考

SpeakerClient / AsyncSpeakerClient

初始化参数：

notify.php — 通知语音播报

同步：client.notify(message, *, id, token, version, seq, vol, speed, trace_no, **kwargs)
异步：await client.async_notify(...)

bind.php — 云音箱绑定/解绑

同步：client.bind(m, uid, *, id, token, version, seq, descs, **kwargs)
异步：await client.async_bind(...)

add.php — 支付语音播报

同步：client.add(price, *, id, token, version, uid, pt, vol, seq, trace_no, descs, suffix, **kwargs)
异步：await client.async_add(...)

modify_bootvoicewav.php — 更改语音信息

同步：client.modify_boot_voice_wav(sound, type, *, id, token, version, off_text, seq, descs, **kwargs)
异步：await client.async_modify_boot_voice_wav(...)

返回码（errcode）

目录结构

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

贡献

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

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

证书

MIT License