Bild-Verarbeitung & Generierungs-Engine API

Das Backend liberino-ai vereint speicherintensive Raster-Bildverarbeitung (via sharp) mit KI-gestützter Generierung, konsistenten Turnaround-Sheets und automatischer Injektion von Universums-Regeln aus Directus (style_templates & lore_entities).

Endpunkt-Übersicht

1. Doppelseiten-Bilder stitchen (POST /api/images/stitch)

Fügt zwei aneinandergrenzende Einzelseiten (z. B. aus illustrierten Kinderbüchern oder Comics) horizontal zu einem nahtlosen Breitbild zusammen oder aktualisiert ein vollständiges HTML-Dokument mit verknüpften Bildreferenzen.

curl -X POST http://localhost:3005/api/images/stitch \
  -H "Content-Type: application/json" \
  -d '{
    "imageABase64": "<base64_linke_seite>",
    "imageBBase64": "<base64_rechte_seite>"
  }'

{
  "success": true,
  "data": {
    "width": 2400,
    "height": 1600,
    "mimeType": "image/png",
    "bufferBase64": "data:image/png;base64,...",
    "sizeBytes": 1420500
  }
}

1.1 Kanten-Gradientenanalyse & Pixelgenaue Ausrichtung

Bei unterschiedlichen Seitenhöhen (z. B. wenn eine Buchseite Text enthält und die Nachbarseite vollflächig illustriert ist) nutzt der Ingestion-Stitcher eine zweistufige Ausrichtung:

1. Grobe Fingerprint-Kandidatenerkennung: Überprüfung von Kantenvarianz und Farbkompatibilität im Thumbnail-Raum.
2. 1D-Farbgradienten-Kreuzkorrelation (Full-Resolution): Entlang der 3px breiten Schnittnaht werden der Farbwert $C(y)$ sowie die 1. vertikale Ableitung (der Farbgradient $\nabla_y C(y) = C(y+1) - C(y)$) berechnet. Durch Minimierung von $|C_A - C_B| + \lambda |\nabla_y C_A - \nabla_y C_B|$ wird der exakte vertikale Versatz $\Delta y$ pixelgenau ermittelt, sodass Horizonte, Bergkämme und Wasserlinien nahtlos zusammenpassen.
3. Visuelle Objekterkennung auf Panoramabildern: Zusammengesetzte Doppelseiten (is_stitched: true) werden unmittelbar in voller Panorama-Breite durch die Vision-Pipeline analysiert. Hierbei verhindert eine gezielte Token-Budget-Optimierung (thinking: { budget_tokens: 0 }), dass Reasoning-Tokens das Ausgabebudget aufbrauchen. Ein robuster JSON-Stream-Parser (robustParseEntityJson) rettet auch bei komplexen Wimmelszenen alle vollständig generierten Bounding Boxes für Charaktere, Fahrzeuge, Gegenstände und Landmarken.

2. Bilder zu WebP komprimieren (POST /api/images/compress)

Konvertiert PNG-, JPEG- oder GIF-Bilder mit einstellbarer Qualität in moderne, hochkomprimierte WebP-Dateien und liefert detaillierte Einsparungsstatistiken.

curl -X POST "http://localhost:3005/api/images/compress?quality=80&effort=4" \
  -F "file=@/pfad/zu/bild.png"

{
  "success": true,
  "data": {
    "filename": "bild.webp",
    "originalSizeBytes": 450120,
    "compressedSizeBytes": 68400,
    "savingsPercent": 85,
    "mimeType": "image/webp",
    "bufferBase64": "data:image/webp;base64,..."
  }
}

3. Bildgenerierung mit Stil- & Lore-Injektion (POST /api/images/generate)

Erzeugt eine Illustration basierend auf einem Benutzereingabetext. Das Backend liest automatisch die hinterlegten Stil-Modifier des gewählten style_template und die visuellen Merkmale (visualTraits) der beteiligten lore_entities aus Directus aus und webt sie nahtlos in den Prompt ein.

curl -X POST http://localhost:3005/api/images/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Mira sitzt mit ihrem treuen Begleiter Jaro am abendlichen Lagerfeuer am Strand.",
    "styleName": "Aquarell",
    "entityIds": ["e1a2b3c4-d5e6-7f8a-9b0c-1d2e3f4a5b6c"],
    "aspectRatio": "16:9"
  }'

Antwort:

{
  "success": true,
  "data": {
    "imageBase64": "...",
    "mimeType": "image/png",
    "promptUsed": "Mira sitzt mit ihrem treuen Begleiter Jaro am abendlichen Lagerfeuer am Strand., Key character details (Mira: Braunes Haar, Lederstiefel, Messingkompass), Style: Hand-painted watercolor illustration, warm soft lighting",
    "negativePromptUsed": "text, watermark, signature, deformed limbs, blurry",
    "styleApplied": "Aquarell",
    "entitiesInjected": ["Mira"]
  }
}

4. 3-Ansichten Turnaround Referenzbögen (POST /api/images/generate-ref-sheets)

Erstellt standardisierte Modellbögen (Frontansicht, 3/4-Profil und Rückansicht) auf reinweißem Studiohintergrund für Figuren und Requisiten.

curl -X POST http://localhost:3005/api/images/generate-ref-sheets \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mira",
    "type": "character",
    "visualTraits": "Junge Entdeckerin, braunes schulterlanges Haar, Lederjacke und Messingkompass",
    "styleName": "Aquarell"
  }'

5. Szenen-Prompt-Vorschläge (POST /api/images/suggest-prompt)

Analysiert einen Buchabschnitt mit dem ROUTER_MODEL und leitet daraus Kameraeinstellung, Beleuchtung, Interaktion der Charaktere und Farbgebung ab.

curl -X POST http://localhost:3005/api/images/suggest-prompt \
  -H "Content-Type: application/json" \
  -d '{
    "passage": "Mira blickte ehrfürchtig in die finstere Meeresgrotte, aus der ein sanftes blaues Glimmen drang.",
    "styleName": "Aquarell"
  }'

6. Pixelgenauer Bounding-Box-Zuschnitt (POST /api/images/crop)

Schneidet ein Segment aus einer Original-Illustration anhand von normierten (0-1000) oder absoluten Bounding-Box-Koordinaten mit einstellbarem Padding aus.

curl -X POST http://localhost:3005/api/images/crop \
  -H "Content-Type: application/json" \
  -d '{
    "imageBase64": "data:image/jpeg;base64,...",
    "box2d": [150, 200, 750, 600],
    "padding": 20
  }'

7. Prompt-Verfeinerung & Re-Prompting (POST /api/images/re-prompt)

Nimmt einen bestehenden Bild-Prompt entgegen und passt Beleuchtung, Detailgrad oder dramatische Stimmung basierend auf Instruktionen an.

curl -X POST http://localhost:3005/api/images/re-prompt \
  -H "Content-Type: application/json" \
  -d '{
    "originalPrompt": "Mira am Hafen",
    "instructions": "Mehr Abendlicht, dramatischer Sonnenuntergang und detailreiches Wasser."
  }'

8. Referenzbilder suchen (GET /api/images/search)

Durchsucht die kuratierte reference_images-Sammlung in Directus nach Stichwort oder Kategorie.

curl "http://localhost:3005/api/images/search?q=mira&limit=10"