High-Performance EPUB-Parsing, automatische Kapitelerkennung, Rausch- und Werbefilterung sowie locale-bewusste Satz- und Szenensegmentierung.

Buch-Ingest & EPUB-Parsing API

Die Buch-Ingest API im liberino-ai-Dienst übernimmt die rechenintensive und speicherlastige Verarbeitung von E-Books im EPUB-Format. Statt ZIP-Archive und XML-Bäume auf Next.js-Frontend-Knoten auf Festplatte zu schreiben, parst der Dienst alle Dokumente vollständig in-memory, führt linguistische Segmentierungen durch und persistiert die Buchstrukturen auf Wunsch direkt in Directus.

Kernfunktionen

In-Memory Extraktion:
- Dekomprimierung von EPUB-Archiven via AdmZip ohne temporäre Dateirückstände.
- Robustes XML-Parsing von container.xml, OPF (Spine, Manifest, Metadaten) und Deckblatt (coverImage).
Automatische Spracherkennung & Sprach-Mappings:
- Erkennt die Sprache über Metadaten (dc:language) oder statistische Stop-Wort-Analyse (detectLanguage).
- Lädt sprachspezifische Regeln aus modularen Mappings (src/config/languages/{lang}.ts).
- Zero-Fallback: Nicht unterstützte Sprachen werfen einen klaren Fehler UnsupportedLanguageError (HTTP 422).
Universelle Rausch- & Werbefilterung:
- Erkennt und isoliert Impressum, Copyright, Inhaltsverzeichnisse und Autoren-Biografien sprachspezifisch.
- Entfernt Verlags-Werbeseiten, Backlists und Newsletter-Aufrufe ohne buchspezifische Sonderregeln.
Locale-bewusste Satzsegmentierung:
- Nutzt die standardisierte Intl.Segmenter Engine für die jeweilige Sprache.
- Saubere Dialog- und Zitatbehandlung anhand der sprachspezifischen quotePairs (z. B. »...«, “...”).
Szenen-Gliederung:
- Strukturierung von Kapiteln in handliche narrative Einheiten (scenes) anhand von Szenentrennern oder Wortanzahl-Schwellwerten.
Directus-Persistierung (optional):
- Synchrones Anlegen der Hierarchie books ➔ chapters ➔ scenes.

1. EPUB-Buch importieren (`POST /api/books/ingest`)

Nimmt ein EPUB-Archiv entgegen und gibt ein strukturiertes JSON-Objekt mit allen Metadaten, Kapiteln, Szenen, Sätzen und Bildreferenzen zurück.

Anfragemodi

Ideal für Direkt-Uploads aus Web-UIs oder Formular-Inputs.

curl -X POST http://localhost:3005/api/books/ingest \
  -F "file=@/pfad/zu/buch.epub" \
  -F "persistToDirectus=false" \
  -F "targetWordsPerScene=350" \
  -F "filterPromos=true"

Optionen (`options`)

Parameter	Typ	Standard	Beschreibung
`persistToDirectus`	`boolean`	`false`	Legt Buch, Kapitel und Szenen direkt in Directus an.
`authorId`	`UUID`	`null`	Optionale Verknüpfung zu einem bestehenden Autor in Directus.
`seriesId`	`UUID`	`null`	Optionale Zuordnung zu einer Buchserie in Directus.
`language`	`string`	(automatisch)	Optionale explizite Quellsprache. Fehlt der Wert, ermittelt die automatische Spracherkennung die Sprache aus Metadaten und Text (z. B. `"de"`, `"en"`).
`targetLanguage`	`string`	(Buchsprache)	Optionale Zielsprache für alle extrahierten Lore-Profile, Szenenreferenzen und visuellen Merkmale (z. B. `"en"`, `"de"`, `"es"`, `"fr"`). Fehlt der Wert, wird standardmäßig direkt die Originalsprache des Buches verwendet.
`targetWordsPerScene`	`number`	`350`	Ziel-Wortanzahl zur Aufteilung langer Fließtexte in Szenen.
`filterPromos`	`boolean`	`true`	Schließt Werbe- und Vorschauseiten des Verlags sprachspezifisch aus.
`includeImages`	`boolean`	`true`	Extrahiert eingebettete Bild-Assets inklusive Base64-Vorschau.

Fehlerfall: Nicht unterstützte Sprache (`422 Unprocessable Entity`)

Wird ein Buch in einer Sprache eingeliefert, für die noch keine Mapping-Datei in src/config/languages/ hinterlegt ist, bricht der Aufruf sofort fail-fast mit einem informativen Hinweis ab:

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "Erkannte Buchsprache 'fr' wird vom System noch nicht durch ein Sprach-Mapping unterstützt. Unterstützte Sprachen sind derzeit: ['de', 'en']. Bitte hinterlegen Sie die Mapping-Datei 'src/config/languages/fr.ts' mit den entsprechenden linguistischen Regeln."
}

Beispiel-Antwort

{
  "success": true,
  "data": {
    "metadata": {
      "title": "Das Geheimnis des Zauberwalds",
      "creator": "Erika Mustermann",
      "language": "de",
      "publisher": "Musterverlag",
      "description": "Ein spannendes Abenteuer im tiefen Wald.",
      "coverImageHref": "images/cover.jpg",
      "coverImageBase64": "data:image/jpeg;base64,..."
    },
    "chapters": [
      {
        "chapterNumber": 1,
        "title": "Die Entdeckung",
        "href": "chapter1.xhtml",
        "wordCount": 420,
        "isPromo": false,
        "scenes": [
          {
            "sceneNumber": 1,
            "title": "Szene 1",
            "rawText": "»Komm schnell mit!«, rief die Gefährtin leise...",
            "sentences": [
              "»Komm schnell mit!«, rief die Gefährtin leise.",
              "Die Morgensonne schien sanft durch das Blätterdach.",
              "Am Waldrand blieb sie stehen."
            ],
            "wordCount": 210,
            "imageRefs": ["illustration-1.png"]
          }
        ],
        "images": [
          {
            "id": "aWxsdXN0cmF0aW9uLTEucG5n",
            "filename": "illustration-1.png",
            "mediaType": "image/png",
            "sizeBytes": 45210,
            "dataBase64": "data:image/png;base64,..."
          }
        ]
      }
    ],
    "stats": {
      "totalChapters": 12,
      "totalScenes": 28,
      "totalSentences": 340,
      "totalWords": 5600,
      "totalImages": 14
    },
    "directus": {
      "bookId": "2f19b992-8cc5-4e54-9b30-007db2670077",
      "chapterIds": ["..."],
      "sceneIds": ["..."]
    }
  }
}

2. Text segmentieren (`POST /api/books/segment`)

Zerlegt isolierten Fließtext in präzise Sätze und narrative Szenenblöcke.

curl -X POST http://localhost:3005/api/books/segment \
  -H "Content-Type: application/json" \
  -d '{
    "text": "»Aufwachen!«, rief der Gefährte. Die Morgensonne tauchte das Tal in goldenes Licht.\n\nSie machten sich sofort auf den Weg zum Pass.",
    "language": "de",
    "targetWordsPerScene": 250
  }'

3. Buch-Details abrufen (`GET /api/books/:id`)

Ruft ein persistiertes Buch aus Directus inklusive aller verknüpften Kapitel und Szenen ab.

curl -X GET http://localhost:3005/api/books/2f19b992-8cc5-4e54-9b30-007db2670077

4. Buch als `.dream` Archiv exportieren (`POST /api/books/package/export`)

Bündelt Buch-HTML, Manifest-Metadaten, Lore-Entitäten und Bilder in ein portables .dream-ZIP-Paket.

curl -X POST http://localhost:3005/api/books/package/export \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Chroniken des Tals",
    "author": "Erika Mustermann",
    "html": "<h1>Kapitel 1</h1><p>Text...</p>",
    "visualStyle": "Malerischer Aquarellstil",
    "characters": [{ "id": "char-protagonist", "name": "Protagonist" }],
    "images": [{ "filename": "cover.png", "base64": "..." }],
    "download": false
  }'

5. `.dream` Archiv importieren & entpacken (`POST /api/books/package/import`)

Liest ein bestehendes .dream-Paket ein, extrahiert alle Metadaten, Buchinhalte und Bilder und legt das Buch optional direkt in Directus an.

curl -X POST http://localhost:3005/api/books/package/import \
  -F "file=@/pfad/zu/buch.dream" \
  -F "persistToDirectus=true"

6. Directus-Buch 1-Click Export (`POST /api/books/export-directus/:bookId`)

Generiert aus einem bestehenden Directus-Buch inklusive aller Kapitel, Szenen und Universums-Entitäten vollautomatisch ein herunterladbares .dream-Archiv.

curl -X POST http://localhost:3005/api/books/export-directus/2f19b992-8cc5-4e54-9b30-007db2670077

Buch-Ingest & EPUB-Parsing

On this page