API HTTP de la MuPiBox
La interfaz HTTP local de la caja: consultar el estado, controlar la reproducción y enviar avisos y mensajes, con ejemplos para curl y domótica.
La MuPiBox tiene una API HTTP local. La usan la interfaz táctil, la administración y la app MuPiBox, y tú puedes usarla para tus propios scripts o tu domótica. Todas las direcciones empiezan por http://<caja>:8090/api/ (caja = dirección IP o nombre, ver Primer arranque). Las respuestas son JSON.
Acceso y seguridad
| Ámbito | ¿Quién puede acceder? |
|---|---|
Reproductor y estado (/api/status, /api/command, /api/speak, /api/message …) | cualquier dispositivo de la red doméstica, sin iniciar sesión |
Administración (/api/admin/…) | solo con sesión de administración cuando hay una contraseña de administración |
Red (/api/connectivity/…) | desde la red doméstica solo con sesión de administración |
Interfaz de Home Assistant (/api/ha/v1/…) | solo por HTTPS (puerto 8443) con un token emparejado; la usa la integración |
La caja bloquea las peticiones de escritura que llegan desde otras webs en un navegador. Los scripts como curl o los sistemas domóticos no envían ese origen de navegador y están permitidos.
Consultar el estado
| Método y ruta | Devuelve |
|---|---|
GET /api/health | {"status":"ok","version":"…"}, ideal para comprobar si la caja responde |
GET /api/status | estado del reproductor: state (playing, paused, stopped, error), folder, queue, index, position, duration (segundos), volume, max_volume, now_playing (título de radio) |
GET /api/info | versión, idioma y los ajustes que necesitan las interfaces |
GET /api/library | biblioteca local con carpetas (id, name) y pistas |
GET /api/home | categorías y medios de la pantalla de inicio |
GET /api/mupihat/status | batería, carga y tensión con el MuPiHAT |
GET /api/system/metrics | CPU, memoria, almacenamiento y temperatura |
curl http://mupibox.local:8090/api/statusControlar la reproducción
POST /api/command con un objeto JSON. El campo action elige la orden:
action | Otros campos | Efecto |
|---|---|---|
toggle | – | alternar reproducción/pausa |
play, pause, stop | – | reproducir, pausar, detener |
next, previous | – | pista siguiente o anterior |
seek | value (segundos) | saltar a una posición |
volume | value (0 hasta el volumen máximo) | fijar el volumen |
volume_delta | value (p. ej. 5 o -5) | cambiar el volumen de forma relativa |
folder | folder_id | iniciar una carpeta/audiocuento desde el principio |
resume | folder_id, item_index | iniciar una carpeta en una pista concreta (0 = primera) |
El folder_id aparece en GET /api/library. El volumen siempre se limita al volumen máximo configurado, y los ajustes del control parental también pueden limitar las órdenes de la API.
# Reproducir/pausar
curl -X POST -H 'Content-Type: application/json' \
-d '{"action":"toggle"}' http://mupibox.local:8090/api/command
# Volumen a 30
curl -X POST -H 'Content-Type: application/json' \
-d '{"action":"volume","value":30}' http://mupibox.local:8090/api/commandAvisos y mensajes
| Método y ruta | JSON | Efecto |
|---|---|---|
POST /api/speak | {"text":"¡A cenar!"} | lee el texto con la voz configurada; la música se pausa y continúa después |
POST /api/message | {"title":"Hola","message":"Pronto a dormir","duration_ms":8000} | muestra un mensaje en la pantalla (title y duration_ms opcionales) |
curl -X POST -H 'Content-Type: application/json' \
-d '{"text":"¡No olvides lavarte los dientes!"}' http://mupibox.local:8090/api/speakEl primer aviso de una frase puede tardar unos segundos porque la caja genera primero la voz; las frases repetidas salen de la caché.
Errores y respuestas
Los errores llegan como JSON {"error":"…"} con el estado HTTP adecuado: 400 (petición incorrecta), 401 (hace falta iniciar sesión), 403 (no permitido), 409 (no es posible ahora, p. ej. sin contraseña de administración), 503 (servicio no disponible).