Muro Box 正式支持开放 API。
通过API密钥认证，第三方服务和自动化工具（如Home Assistant、IFTTT或您自己的自定义脚本）可以直接控制您的音乐盒：播放歌曲和播放列表、停止播放、调整设备设置，以及搜索歌曲和播放列表目录。
所有播放均在音乐盒本体上进行。API 不返回 MIDI 文件或下载链接，从而确保音乐内容的版权保护与完整性。
你可以用 API 做什么？
- 播放单首歌曲 (
play_song) - 播放播放列表；系统根据账户权限自动筛选可播放的歌曲 (
play_playlist) - 停止当前播放 (
stop_playing) - 读取和更新设备设置：电机速度、随机播放模式、最大播放时间、MIDI输出、蓝牙MIDI开关 (
device_settings) - 搜索歌曲和播放列表，支持关键词、分页及多语言名称 (
search/songs,search/packages)
三步入门
- 打开Muro Box App → 设置 → API密钥 → 添加。为密钥命名并确认。完整密钥仅显示一次，请立即复制并保存（之后无法再次查看）。
- 请在 App 的设备设置页面中找到您的设备序列号（
device_sn）。 - 调用API：向
https://api.murobox.com/muro_api/v1/...发送POST请求，并在请求头中携带你的API密钥。
curl -X POST https://api.murobox.com/muro_api/v1/devices/play_song/
-H "api-key: YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{"device_sn": "YOUR_DEVICE_SN", "song_id": "SONG_ID"}'
歌曲ID（song_id）和播放列表ID（playlist_id）可以直接在App中复制：在播放器菜单中选择“复制歌曲ID”，或在播放列表详情页中选择“复制播放列表ID”。
安全与使用说明
- API密钥等同于密码。服务器仅存储SHA-256指纹，无法恢复原始密钥。请勿分享。
- 每个密钥每分钟最多允许60次请求（超过此限制将返回HTTP 429）。
- 钥匙仅能控制绑定至同一账户的音乐盒；无法用于下载歌曲或MIDI文件。
- 如需完整的接口文档以及可直接导入的 Postman Collection，请参阅 Muro Box Open API 用户指南。
