Muro Box가 Open API를 공식 지원합니다.
API 키 인증을 사용하면 Home Assistant, IFTTT 또는 직접 작성한 스크립트와 같은 제3자 서비스 및 자동화 도구가 사용자의 오르골을 직접 제어할 수 있습니다. 이러한 서비스와 도구는 곡과 재생 목록을 재생하고, 재생을 중지하며, 기기 설정을 조정하고, 곡 및 재생 목록 카탈로그를 검색할 수 있습니다.
모든 재생은 오르골 본체에서 이루어집니다. API는 MIDI 파일이나 다운로드 링크를 반환하지 않으며, 이를 통해 저작권 보호와 음악 콘텐츠의 무결성이 보장됩니다.
API로 할 수 있는 작업
- 단일 곡 재생(
play_song) - 재생 목록 재생: 시스템이 계정 권한에 따라 재생 가능한 곡을 자동으로 필터링합니다(
play_playlist) - 현재 재생 중지(
stop_playing) - 기기 설정 조회 및 변경: 모터 속도, 셔플 모드, 최대 재생 시간, MIDI 출력, 블루투스 MIDI 토글 (
device_settings) - 키워드 검색, 페이지네이션, 다국어 이름 지원을 통한 곡 및 플레이리스트 검색 (
search/songs,search/packages)
3단계로 시작하기
- Muro Box App을 열고 설정(Settings) → API Keys → 추가(Add)를 선택합니다. 키 이름을 입력한 후 확인합니다. 전체 키는 한 번만 표시되므로 즉시 복사하여 저장해야 합니다(이후에는 다시 확인할 수 없습니다).
- 앱의 기기 설정 페이지에서 기기 일련번호(
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)는 앱에서 직접 복사할 수 있습니다. 플레이어 메뉴의 “곡 ID 복사” 또는 플레이리스트 상세 페이지의 “플레이리스트 ID 복사”를 이용하십시오.
보안 및 사용상 유의 사항
- API 키는 비밀번호와 동일하게 취급해야 합니다. 서버에는 SHA‑256 지문만 저장되며, 원본 키는 복구할 수 없습니다. 키를 공유해서는 안 됩니다.
- 각 키는 분당 최대 60회의 요청을 허용합니다(이를 초과할 경우 HTTP 429가 반환됩니다).
- 키는 동일한 계정에 연결된 오르골만 제어할 수 있으며, 곡이나 MIDI 파일을 다운로드하는 데에는 사용할 수 없습니다.
- 엔드포인트에 대한 전체 문서와 바로 가져올 수 있는 Postman 컬렉션에 대해서는 Muro Box Open API 사용자 가이드를 참고하십시오.
