EPUBCheck als API

EPUBCheck ist der Konformitätsprüfer des W3C für EPUB-Publikationen. Er prüft den ZIP-Container, das Paketdokument, die Navigation und jedes Inhaltsdokument einer EPUB-2- oder EPUB-3-Datei gegen die EPUB-Spezifikationen. Viele E-Book-Shops und Distributoren verlangen, dass eine Datei die Prüfung besteht, bevor sie sie annehmen.

Hier läuft er hinter einem HTTPS-Endpunkt: Senden Sie die Datei und erhalten Sie den JSON-Bericht von EPUBCheck selbst zurück, dazu eine summary mit dem Ergebnis.

Preis und Limits

Eine Prüfung kostet 2 Credits, unabhängig vom Ergebnis: Eine Datei mit Fehlern ist eine normale Antwort (200), mit den Fehlern in messages. Ein Aufruf, der abgelehnt wird oder fehlschlägt (jeder Status ab 400), kostet nichts. Ohne API-Schlüssel verbraucht eine Prüfung das kostenlose Tageskontingent Ihrer IP-Adresse; das kostenlose Kontingent und die Tarife stehen auf der Preisseite.

• 25 MB pro Datei, eine Datei pro Aufruf.
• 45 Sekunden pro Prüfung. Eine längere Prüfung wird abgebrochen und antwortet mit 504 engine_timeout.
• EPUBCheck führt eine Prüfung gleichzeitig aus. Solange er beschäftigt ist, antwortet ein Aufruf mit 429 engine_busy und einem Retry-After-Header: Warten Sie so viele Sekunden und senden Sie ihn erneut.

Selbst hosten oder gehostet

EPUBCheck kommt als Java-Kommandozeilenwerkzeug. Es selbst zu betreiben heißt eine Java-Laufzeit auf jeder Maschine, die Dateien prüft, das EPUBCheck-Release und seine Updates und eine neue JVM für jede Prüfung: etwa 512 MB Arbeitsspeicher und ein bis zwei Sekunden Startzeit pro Datei. Um es aus einem anderen Dienst aufzurufen, schreiben und betreiben Sie außerdem einen kleinen HTTP-Wrapper darum.

Gehostet ist es ein API-Schlüssel und ein HTTPS-Aufruf, aus jeder Sprache, ohne etwas zu installieren oder zu aktualisieren.

Schnellstart: curl

curl -sS -X POST https://api.pagespool.com/v1/epubcheck/check \
  -H "X-API-Key: $PAGESPOOL_KEY" \
  -F file=@book.epub | jq .summary

summary ist das Ergebnis auf einen Blick:

{"valid": false, "fatal": 0, "error": 2, "warning": 1}

Der Rest der Antwort ist der Bericht von EPUBCheck, so wie EPUBCheck ihn schreibt.

Schnellstart: Python

import httpx

with open("book.epub", "rb") as f:
    resp = httpx.post(
        "https://api.pagespool.com/v1/epubcheck/check",
        headers={"X-API-Key": KEY},
        files={"file": ("book.epub", f, "application/epub+zip")},
        timeout=60,
    )
resp.raise_for_status()
report = resp.json()
print(report["summary"])
for message in report["messages"]:
    print(message["severity"], message["ID"], message["message"])

Die Antwort

Eine Antwort mit 200 ist der JSON-Bericht von EPUBCheck, unverändert, mit einem zusätzlichen Schlüssel:

• checker: die Version von EPUBCheck (checkerVersion) und seine eigenen Zählungen.
• publication: die Metadaten, die EPUBCheck gelesen hat, etwa title, language und ePubVersion.
• items: jede Datei im EPUB, mit ihrem Medientyp.
• messages: ein Eintrag pro Problem, mit ID (zum Beispiel RSC-005), severity, message, locations (path, line, column; -1, wenn unbekannt) und suggestion. EPUBCheck führt alle Stellen eines Problems unter einer Meldung auf.
• summary: valid (keine FATAL- und keine ERROR-Meldung) und die Zahl der fatal-, error- und warning-Meldungen.

Fehler sind RFC-9457-Probleme (application/problem+json) mit einem stabilen code: payload_too_large (413), engine_busy (429), engine_failed (502), engine_unavailable (503, mit Retry-After) und engine_timeout (504).

API-Schlüssel

Ein Schlüssel kommt an eine von drei Stellen:

• in den Header X-API-Key: -H "X-API-Key: $PAGESPOOL_KEY";
• als Bearer-Token: -H "Authorization: Bearer $PAGESPOOL_KEY";
• per HTTP-Basic-Authentifizierung mit dem Schlüssel als Passwort und einem beliebigen Benutzernamen: curl -u "x:$PAGESPOOL_KEY" … oder eine URL wie https://x:<key>@… für einen Client, der nur eine URL annimmt.

Setzen Sie den Schlüssel nie in den Pfad oder den Query-String: Beide landen in Protokollen.

Kostenloses Tool und MCP

Um eine Datei ohne Code zu testen, nutzen Sie den kostenlosen EPUB-Validator (Dateien bis 4 MB).

KI-Agenten erhalten dieselbe Prüfung vom MCP-Server unter https://api.pagespool.com/mcp/epubcheck/. Sein Tool check_epub nimmt die EPUB-Datei als Base64 (bis 4 MB) oder als https-Link an und liefert die Zusammenfassung und die 20 schwersten Meldungen. Es kostet 2 Credits pro Aufruf, wie die API.

Marken

EPUBCheck ist ein Projekt des W3C; pagespool ist mit dem W3C nicht verbunden.

FAQ

Was prüft EPUBCheck?

EPUBCheck prüft eine EPUB-2- oder EPUB-3-Datei gegen die EPUB-Spezifikationen: den ZIP-Container, das Paketdokument, die Navigation und jedes Inhaltsdokument. Jedes gefundene Problem ist eine Meldung mit einem Schweregrad: FATAL, ERROR, WARNING, USAGE oder INFO.

Wann ist eine Datei gültig?

Wenn der Bericht keine FATAL- und keine ERROR-Meldung enthält. Warnungen allein machen eine Datei nicht ungültig. Die summary in jeder Antwort sagt das in valid, neben der Zahl der fatal-, error- und warning-Meldungen.

Brauche ich einen API-Schlüssel?

Nein. Ohne Schlüssel verbraucht eine Prüfung das kostenlose Tageskontingent Ihrer IP-Adresse. Ein kostenloses Konto mit Schlüssel erhält ein eigenes Tageskontingent und monatliche Credits; die Tarife stehen auf der Preisseite.