Vollständige OpenAPI 3.1 Dokumentation, Download-Links und globale Schnittstellen-Standards

OpenAPI 3.1 Spezifikation

Die Schnittstelle des LoreKeeper Service ist vollständig nach dem OpenAPI 3.1 Standard spezifiziert.

Spezifikation herunterladen

Die rohen Spezifikationsdateien stehen direkt im Web-Format zur Verfügung:

🚀 Interaktive Swagger UI öffnen

Alle Endpunkte live im Browser ausführen, Parameter testen und Antworten einsehen.

OpenAPI YAML herunterladen

Vollständige OpenAPI 3.1 Spezifikation im YAML-Format für Postman, Insomnia oder CI/CD.

OpenAPI JSON herunterladen

Maschinenlesbare JSON-Spezifikation für automatische Code-Generatoren.

Server-Endpunkte & Umgebungen

Umgebung	URL	Beschreibung
Lokal (Host)	`http://localhost:3005`	Standardmäßige lokale Entwicklungs-URL
Docker Netzwerk	`http://lorekeeper-api:3005`	Interner Service-Endpunkt im Compose-Netzwerk

Standard-Fehlerformat

Alle Fehlerantworten (z. B. Validierungsfehler oder Server-Exceptions) folgen einer einheitlichen JSON-Struktur:

{
  "error": "Validation failed",
  "details": {
    "bookId": {
      "_errors": ["bookId is required"]
    },
    "prompt": {
      "_errors": ["prompt must be at least 3 characters"]
    }
  }
}

Vollständige Endpunkt-Übersicht

📖 Buch-Ingestion & Status (`/api/books`)

Methode	Pfad	Beschreibung
`POST`	`/api/books/ingest`	Vollautomatisierte 2-Phasen Ingestion (Base64 EPUB oder Remote File ID)
`POST`	`/api/books/ingest/upload`	Multipart-Upload für große E-Books bis 100 MB
`GET`	`/api/books/:id/status`	Abfrage des Ingestion-Fortschritts und Fehlerprotokolls
`GET`	`/api/books/:id/export`	Exportiert das Buch inklusive aller generierten Szenen als EPUB

👤 Entitäten, Bounding-Boxes & Rollen (`/api/entities`)

Methode	Pfad	Beschreibung
`POST`	`/api/entities/extract-visual`	Unüberwachte Bildsegmentierung und Bounding-Box-Generierung
`POST`	`/api/entities/localize`	Übersetzt Entitäten (Namen, Beschreibungen, Merkmale) in die Buchsprache
`POST`	`/api/entities/merge`	Führt mehrere Duplikate/Profile zusammen und aktualisiert Szenen-Referenzen
`POST`	`/api/entities/:id/tier`	Dynamische Anpassung der Figuren-Bedeutung (`main`, `supporting`, `extra`)
`POST`	`/api/entities/:id/refine-bbox`	Automatische Verfeinerung von Zuschnittskanten via Computer Vision
`GET`	`/api/entities`	Abfrage aller Lore-Figuren, Objekte und Orte mit Filtern
`GET`	`/api/entities/:id`	Vollständiger Lore-Steckbrief inklusive kanonischer Eigenschaften
`GET`	`/api/entities/:id/crops`	Alle visuellen Bildsegmente und Vorkommnisse einer Figur

🖼️ Bildverarbeitung & Cropping (`/api/images`)

Methode	Pfad	Beschreibung
`POST`	`/api/images/crop`	Verlustfreier Master-Zuschnitt von Bounding-Boxes auf Originalbildern
`POST`	`/api/images/generate`	Generierung stilkonformer Buchillustrationen via Imagen 4 / Gemini
`POST`	`/api/images/re-prompt`	Synthese konsistenter Prompts basierend auf Figuren-Farbpaletten

✍️ Szenen-Generierung & Audit (`/api/scenes`)

Methode	Pfad	Beschreibung
`POST`	`/api/scenes/generate`	Generiert eine kanontreue Szene via Agentic RAG Pipeline
`POST`	`/api/scenes/audit`	Auditiert einen Szenentext gegen alle Welt- und Figurenregeln
`GET`	`/api/scenes/:id`	Ruft eine gespeicherte Szene direkt aus Directus ab

🤖 Autonomer Agent & Tool-Execution (`/api/agent`)

Methode	Pfad	Beschreibung
`POST`	`/api/agent/chat`	Interaktiver Dialog mit dem autonomen LoreKeeper ReAct-Agenten
`GET`	`/api/agent/tools`	Liste aller registrierten Directus- und Lore-Werkzeuge
`POST`	`/api/agent/tools/execute`	Programmatische Direktausführung eines Agenten-Tools

🎨 Stil-Perspektiven & Systemstatus

Methode	Pfad	Beschreibung
`POST`	`/api/styles/generate-prompt`	Erzeugt optimierte Prompts für Text- und Bildstile
`POST`	`/api/styles/apply`	Wendet Stilvorlagen auf bestehende Manuskripte an
`GET`	`/health`	Live-Healthcheck für Fastify, Directus CMS und LiteLLM Proxy

OpenAPI Spezifikation & Übersicht