Tout ce que font l’appli web et les applis passe par l’API HTTP de ZiiX.TV, et vous pouvez l’utiliser vous aussi : pour des scripts, la domotique ou votre propre client.
La documentation est sur votre serveur
Chaque serveur propose sa référence complète de l’API à l’adresse http://<your server>:8470/docs, avec une recherche, des exemples et le téléchargement de la spécification OpenAPI. Elle est générée à partir de la même spécification que le serveur lui-même, elle correspond donc toujours à votre version. Le lien se trouve en bas de page de l’appli web.
Se connecter
Toutes les requêtes vont vers /api. Connectez-vous avec un nom d’utilisateur et un mot de passe pour obtenir un jeton :
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":"…"}
Envoyez le jeton dans l’en-tête Authorization à chaque requête :
curl http://nas:8470/api/libraries -H 'Authorization: Bearer <token>'
- Un jeton est valable 90 jours, ou jusqu’à sa déconnexion avec
POST /api/auth/logoutou dans Paramètres → Appareils. - Un jeton agit au nom de son utilisateur et voit ce que cet utilisateur voit. Les endpoints des paramètres, des utilisateurs et des bibliothèques exigent un administrateur.
- Utilisez un utilisateur distinct pour un script, afin de pouvoir le déconnecter séparément.
Exemples
# Les bibliothèques, et les titres de la bibliothèque 2
curl http://nas:8470/api/libraries -H "Authorization: Bearer $TOKEN"
curl http://nas:8470/api/libraries/2/titles -H "Authorization: Bearer $TOKEN"
# Reprendre la lecture
curl http://nas:8470/api/continue -H "Authorization: Bearer $TOKEN"
# Marquer un titre comme vu
curl -X PUT http://nas:8470/api/titles/12/watched \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"watched":true}'
# Analyser la bibliothèque 2 maintenant (administrateurs)
curl -X POST http://nas:8470/api/libraries/2/scan -H "Authorization: Bearer $TOKEN"
La lecture d’un fichier se fait en deux étapes : POST /api/files/{id}/playback, avec ce que le client sait lire, indique comment le lire (en direct, réempaqueté ou converti) et l’adresse du flux ; PUT /api/files/{id}/progress enregistre où en est l’utilisateur. La référence donne tous les détails.
Événements en direct
GET /api/events est un WebSocket qui envoie un court message JSON dès que quelque chose change, pour qu’un client puisse se mettre à jour sans redemander sans cesse :
{"type":"titles","libraryId":2}
Les types sont libraries (ajout, suppression, analyse), titles (titres nouveaux ou modifiés), metadata, watch (historique de visionnage) et views.
Erreurs
Les erreurs comportent un code stable pour les programmes et un message pour les humains :
{"code":"unauthorized","error":"log in to use this server"}
| Statut | Code | Signification |
|---|---|---|
| 401 | unauthorized | Pas de jeton, ou le jeton a expiré |
| 403 | forbidden | Nécessite un administrateur |
| 402 | license_required | L’essai ou la licence du serveur a expiré |
| 429 | too_many_attempts | Trop de connexions échouées ; patientez quelques minutes |
| 503 | transcode_busy | Le serveur convertit déjà autant de vidéos qu’il y est autorisé |
Limites
- Après dix connexions échouées pour un même utilisateur depuis une même adresse en cinq minutes, les tentatives sont refusées pendant un moment.
- Le corps des requêtes est en JSON, 64 Ko au maximum.
- Les requêtes provenant d’autres sites web dans un navigateur sont refusées ; les scripts avec un jeton ne sont pas concernés.
Compatibilité
Les nouvelles versions de ZiiX.TV enrichissent l’API mais ne suppriment ni ne renomment ce qui existe : les scripts et les anciennes applis continuent de fonctionner après une mise à jour.