Usar la API

La API HTTP de ZiiX.TV: iniciar sesión con un token, la documentación interactiva en tu servidor, ejemplos con curl, eventos en directo, errores y límites.

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/logout o 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"}
EstadoCódigoSignificado
401unauthorizedNo hay token, o el token ha caducado
403forbiddenRequiere un administrador
402license_requiredLa prueba o la licencia del servidor ha caducado
429too_many_attemptsDemasiados inicios de sesión fallidos; espera unos minutos
503transcode_busyEl 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.