Endpunkte zur Stilauswahl, 3-View-Turnaround-Generierung und kanonischen Freigabe von Charakter-, Objekt- und Orts-Referenzkarten

references`)

Das Referenzkarten-Subsystem ermöglicht Autoren und KI-Agenten die interaktive, visuelle Entwicklung von Charakteren, Requisiten und Schauplätzen:

Stilauswahl: Durchsuchen des 25+ Stile umfassenden Katalogs inklusive lokaler Master-Sheet-Vorlagen (Figuren, Architektur, Landschaft, Gesamtszene).
Turnaround-Generierung: Automatische Erstellung isolierter 3-Ansichten-Modellbögen (Front, 3/4, Back View) auf neutralem Studiopodest unter strikter Einhaltung von Negativ-Regeln.
Visuelle Vorschau & Iteration: Unmittelbare Darstellung der gerenderten Bilder im LLM-Chat (MCP), im Browser oder im Terminal.
Kanonische Fixierung: Speicherung der genehmigten Referenzkarte als kanonisches Avatar- und Look-and-Feel-Vorbild in der Directus Lore-Datenbank.

Endpunkte im Überblick

Methode	Pfad	Beschreibung
`GET`	`/api/references/styles`	Stile mit lokalen Master-Sheet-Vorschauen auflisten
`POST`	`/api/references/generate-card`	Turnaround-Referenzkarte für Figur, Objekt oder Ort generieren
`POST`	`/api/references/approve`	Genehmigte Referenzkarte kanonisch in Directus sperren/speichern
`GET`	`/generated-references/*`	Statische Bereitstellung der generierten Referenzkarten-PNGs

1. Stile auflisten (`GET /api/references/styles`)

Liefert alle Stile aus Directus und dem lokalen Musterkatalog, angereichert mit Pfaden zu vorhandenen 4-fach-Master-Sheets.

Parameter (Query)

type (optional): illustration | text
search (optional): Freitext-Suche nach Name, Stilbeschreibung oder Schlagwörtern

Beispiel-Antwort

{
  "success": true,
  "count": 28,
  "styles": [
    {
      "id": "whimsical-storybook",
      "slug": "whimsical-storybook",
      "name": "Whimsical Storybook (Klassisches Bilderbuch)",
      "category": "illustration",
      "description": "Warme Aquarell- und Buntstift-Ästhetik mit sanften Konturen und freundlicher Atmosphäre.",
      "promptModifier": "Art style: Whimsical children's book illustration, soft watercolor and color pencil textures...",
      "tags": ["watercolor", "whimsical", "children", "classic"],
      "sampleMasterSheets": [
        "/Users/.../web/references/illustration/sample-images/whimsical-storybook/master-sheet-1.png",
        "/Users/.../web/references/illustration/sample-images/whimsical-storybook/master-sheet-2.png"
      ]
    }
  ]
}

2. Referenzkarte generieren (`POST /api/references/generate-card`)

Erzeugt einen Turnaround-Modellbogen (z. B. Front, 3/4-Ansicht, Rückansicht) auf weißem Hintergrund und erfasst die anfallenden Bildgenerierungskosten im 24h-Ledger.

Request Body

{
  "entityName": "Balthasar",
  "entityType": "character",
  "description": "Ein neugieriger kleiner Walddachs mit gestreiftem Fell und einer alten Gelehrtenbrille.",
  "visualTraits": "grau-weißes Fell, runde Nickelbrille, moosgrüne Weste mit Messingknöpfen",
  "negativeRules": ["keine Flügel", "keine Waffen", "kein Mensch"],
  "styleIdOrSlug": "whimsical-storybook",
  "aspectRatio": "1:1"
}

Response Body (`200 OK`)

{
  "success": true,
  "card": {
    "cardId": "ref_balthasar_1729000000000",
    "entityName": "Balthasar",
    "entityType": "character",
    "styleApplied": "Whimsical Storybook",
    "imageFilename": "ref_balthasar_1729000000000.png",
    "imagePath": "/Users/.../public/generated-references/ref_balthasar_1729000000000.png",
    "imageUrl": "/generated-references/ref_balthasar_1729000000000.png",
    "imageBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "mimeType": "image/png",
    "markdownEmbed": "![Referenzkarte: Balthasar](file:///Users/.../public/generated-references/ref_balthasar_1729000000000.png)"
  }
}

3. Referenzkarte kanonisch genehmigen (`POST /api/references/approve`)

Verknüpft die freigegebene Bilddatei mit dem lore_entities-Datensatz in Directus (static_traits.canonical_reference_image_path).

Request Body

{
  "entityIdOrName": "Balthasar",
  "imagePathOrFilename": "/Users/.../public/generated-references/ref_balthasar_1729000000000.png",
  "visualTraitsSnippet": "Kanonisches Aussehen: Dachs mit Nickelbrille und Messingknopf-Weste",
  "exactColors": "Fell: #4A4A4A / #FFFFFF, Weste: #3B5323"
}

Response Body (`200 OK`)

{
  "success": true,
  "entityId": "a1b2c3d4-...",
  "entityName": "Balthasar",
  "imagePath": "/Users/.../public/generated-references/ref_balthasar_1729000000000.png",
  "canonicalAvatarUrl": "/generated-references/ref_balthasar_1729000000000.png",
  "message": "Referenzkarte für \"Balthasar\" erfolgreich genehmigt und als kanonische Vorlage gespeichert!"
}

Referenzkarten & Iterative Bildentwicklung

On this page