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：將您的API金鑰放在標頭中，向
https://api.murobox.com/muro_api/v1/...發送POST請求。
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 使用者指南。
