Todo lo que hacen la app web y las apps pasa por la API HTTP de ZiiX.TV, y tú también puedes usarla: para scripts, domótica o tu propio cliente.
La documentación está en tu servidor
Cada servidor tiene su referencia completa de la API en http://<your server>:8470/docs, con búsqueda, ejemplos y la especificación OpenAPI para descargar. Se genera a partir de la misma especificación que el propio servidor, así que siempre coincide con tu versión. El enlace está en el pie de página de la app web.
Iniciar sesión
Todas las peticiones van a /api. Inicia sesión con un nombre de usuario y una contraseña para obtener un token:
curl -X POST http://nas:8470/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"username":"anna","password":"…"}'
{"user":{"id":1,"username":"anna","isAdmin":true},"token":"…"}
Envía el token en la cabecera Authorization con cada petición:
curl http://nas:8470/api/libraries -H 'Authorization: Bearer <token>'
- Un token vale durante 90 días, o hasta que se cierra su sesión con
POST /api/auth/logouto en Ajustes → Dispositivos. - Un token actúa como su usuario y ve lo que ve ese usuario. Los endpoints de ajustes, usuarios y bibliotecas requieren un administrador.
- Usa un usuario aparte para cada script, para poder cerrar su sesión por separado.
Ejemplos
# Las bibliotecas, y los títulos de la biblioteca 2
curl http://nas:8470/api/libraries -H "Authorization: Bearer $TOKEN"
curl http://nas:8470/api/libraries/2/titles -H "Authorization: Bearer $TOKEN"
# Seguir viendo
curl http://nas:8470/api/continue -H "Authorization: Bearer $TOKEN"
# Marcar un título como visto
curl -X PUT http://nas:8470/api/titles/12/watched \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"watched":true}'
# Escanear ahora la biblioteca 2 (administradores)
curl -X POST http://nas:8470/api/libraries/2/scan -H "Authorization: Bearer $TOKEN"
Reproducir un archivo son dos pasos: POST /api/files/{id}/playback, con lo que el cliente puede reproducir, devuelve cómo reproducirlo (directamente, reempaquetado o convertido) y la dirección del stream; PUT /api/files/{id}/progress guarda dónde va el usuario. La referencia tiene los detalles.
Eventos en directo
GET /api/events es un WebSocket que envía un mensaje JSON corto cada vez que algo cambia, para que un cliente se actualice sin tener que preguntar una y otra vez:
{"type":"titles","libraryId":2}
Los tipos son libraries (añadida, quitada, escaneando), titles (títulos nuevos o cambiados), metadata, watch (historial) y views.
Errores
Los errores tienen un código estable para los programas y un mensaje para las personas:
{"code":"unauthorized","error":"log in to use this server"}
| Estado | Código | Significado |
|---|---|---|
| 401 | unauthorized | No hay token, o el token ha caducado |
| 403 | forbidden | Requiere un administrador |
| 402 | license_required | La prueba o la licencia del servidor ha caducado |
| 429 | too_many_attempts | Demasiados inicios de sesión fallidos; espera unos minutos |
| 503 | transcode_busy | El servidor ya está convirtiendo todos los videos que tiene permitidos |
Límites
- Diez inicios de sesión fallidos para un usuario desde una misma dirección en cinco minutos se rechazan durante un tiempo.
- Los cuerpos de las peticiones son JSON, de 64 KB como máximo.
- Las peticiones desde otros sitios web en un navegador se rechazan; los scripts con token no se ven afectados.
Compatibilidad
Las nuevas versiones de ZiiX.TV añaden cosas a la API, pero no quitan ni renombran lo que ya existe, así que los scripts y las apps antiguas siguen funcionando después de una actualización.