Die API nutzen

Die HTTP-API des Medienservers ZiiX.TV: Anmeldung mit Token, interaktive Dokumentation auf deinem Server, Beispiele mit curl, Live-Events, Fehler und Limits.

Alles, was die Web-App und die Apps tun, läuft über die HTTP-API von ZiiX.TV, und du kannst sie auch nutzen: für Skripte, Hausautomation oder einen eigenen Client.

Die Dokumentation liegt auf deinem Server

Jeder Server hat seine vollständige API-Referenz unter http://<your server>:8470/docs, mit Suche, Beispielen und einem Download der OpenAPI-Spezifikation. Sie wird aus derselben Spezifikation erzeugt wie der Server selbst und passt daher immer zu deiner Version. Der Link steht in der Fußzeile der Web-App.

Anmelden

Alle Anfragen gehen an /api. Melde dich mit Benutzername und Passwort an, um ein Token zu bekommen:

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":"…"}

Schick das Token bei jeder Anfrage im Header Authorization mit:

curl http://nas:8470/api/libraries -H 'Authorization: Bearer <token>'
  • Ein Token gilt 90 Tage oder bis es mit POST /api/auth/logout oder unter Einstellungen → Geräte abgemeldet wird.
  • Ein Token handelt als sein Benutzer und sieht, was dieser Benutzer sieht. Endpunkte für Einstellungen, Benutzer und Mediatheken brauchen einen Administrator.
  • Nimm für ein Skript einen eigenen Benutzer, damit es sich separat abmelden lässt.

Beispiele

# Die Mediatheken und die Titel in Mediathek 2
curl http://nas:8470/api/libraries -H "Authorization: Bearer $TOKEN"
curl http://nas:8470/api/libraries/2/titles -H "Authorization: Bearer $TOKEN"

# Weiterschauen
curl http://nas:8470/api/continue -H "Authorization: Bearer $TOKEN"

# Einen Titel als gesehen markieren
curl -X PUT http://nas:8470/api/titles/12/watched \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"watched":true}'

# Mediathek 2 jetzt scannen (Administratoren)
curl -X POST http://nas:8470/api/libraries/2/scan -H "Authorization: Bearer $TOKEN"

Eine Datei abzuspielen geht in zwei Schritten: POST /api/files/{id}/playback mit dem, was der Client abspielen kann, liefert, wie sie abgespielt wird (direkt, neu verpackt oder umgewandelt), und die Adresse des Streams; PUT /api/files/{id}/progress speichert, wo der Benutzer gerade ist. Die Details stehen in der Referenz.

Live-Events

GET /api/events ist ein WebSocket, der eine kurze JSON-Nachricht sendet, sobald sich etwas ändert, damit ein Client sich aktualisieren kann, ohne immer wieder nachzufragen:

{"type":"titles","libraryId":2}

Die Typen sind libraries (hinzugefügt, entfernt, Scan läuft), titles (neue oder geänderte Titel), metadata, watch (Wiedergabeverlauf) und views.

Fehler

Fehler haben einen stabilen Code für Programme und eine Meldung für Menschen:

{"code":"unauthorized","error":"log in to use this server"}
StatusCodeBedeutung
401unauthorizedKein Token, oder das Token ist abgelaufen
403forbiddenErfordert einen Administrator
402license_requiredTestphase oder Lizenz des Servers ist abgelaufen
429too_many_attemptsZu viele fehlgeschlagene Anmeldungen; warte ein paar Minuten
503transcode_busyDer Server wandelt bereits so viele Videos um, wie er darf

Limits

  • Nach zehn fehlgeschlagenen Anmeldungen für einen Benutzer von einer Adresse innerhalb von fünf Minuten werden weitere Versuche eine Zeit lang abgelehnt.
  • Anfragen haben einen JSON-Body von höchstens 64 KB.
  • Anfragen von anderen Websites im Browser werden abgelehnt; Skripte mit Token sind davon nicht betroffen.

Kompatibilität

Neue Versionen von ZiiX.TV erweitern die API, entfernen oder benennen aber nichts Bestehendes um, damit Skripte und ältere Apps nach einem Update weiter funktionieren.