KI-Bildvorschläge einrichten und betreiben

Diese Anleitung richtet sich an Personen, die das CMS betreiben. Der Ablauf für die Redaktion steht unter Medien und Alternativtexte.

Aktivieren und Anbieter wählen

Bildvorschläge sind standardmäßig deaktiviert. Konfigurieren Sie einen Anbieter als Laufzeitumgebung des CMS und starten Sie das CMS danach neu.

# Beispiel: fal.ai
IMAGE_GENERATION_ENABLED=true
IMAGE_PROVIDER=fal
FAL_KEY=<serverseitiges-secret>
FAL_IMAGE_MODEL=openai/gpt-image-2/edit

Für eine lokale Installation auf macOS mit Apple Silicon kann stattdessen IMAGE_PROVIDER=mflux mit einem installierten MFLUX und dem Modell black-forest-labs/FLUX.2-klein-4B verwendet werden. Ein kompatibler eigener HTTP-Endpunkt ist mit IMAGE_PROVIDER=http, IMAGE_HTTP_API_URL und IMAGE_HTTP_MODEL möglich. Die Konfiguration, Modell-Auswahl und alle optionalen Parameter stehen unter Umgebungsvariablen: Bildvorschläge. Der API-Key bleibt ausschließlich serverseitig. Bei externen Anbietern prüft der Betreiber Vertrag, Datenverarbeitung und aktuelle Kosten.

Modelle und Referenzen

Bei fal.ai können Sie mit FAL_IMAGE_MODELS mehrere vollständig konfigurierte Modelle für die Auswahl im CMS freigeben. FAL_IMAGE_MODEL legt den Standard fest und muss dann in dieser Liste stehen. Ohne Allowlist erscheint nur das Standardmodell. Die Qualitätsstufe FAL_IMAGE_QUALITY gilt für GPT Image 2; FLUX Kontext Pro ignoriert sie. Modellnamen und API-Key stammen aus der Serverkonfiguration und können von der Redaktion nicht frei an den Anbieter übergeben werden.

FAL_IMAGE_MODEL=openai/gpt-image-2/edit
FAL_IMAGE_MODELS=openai/gpt-image-2/edit,fal-ai/flux-pro/kontext/multi
FAL_IMAGE_QUALITY=medium

Wählen Sie die Stilreferenzen im CMS unter Einstellungen → Bildreferenzen aus der Mediathek: getrennt für Kategorie- und Story-Icons sowie Bilder in Text-Slides. Die Auswahl wird in der jeweiligen CMS-Datenbank gespeichert. Für fal muss mindestens ein nutzbares Referenzbild vorhanden sein; wählen Sie daher in jeder Umgebung eigene Bilder aus. Eine Medien-ID gilt nur in der Datenbank, aus der sie stammt, und kann nach einem Neuimport anders sein. Fehlende Bilder werden in den Einstellungen markiert und müssen ersetzt werden. Die Auswahl ist auf vier Bilder je Profil begrenzt.

Optional können AI_IMAGE_ICON_REFERENCE_MEDIA_IDS und AI_IMAGE_STORY_REFERENCE_MEDIA_IDS die Anfangsauswahl vorgeben. Sobald Sie die Seite erstmals speichern, gilt stattdessen die dort gespeicherte Auswahl; auch eine leere Auswahl übersteuert dann die ENV-Werte. Das bereits im gewählten Feld verwendete Bild wird zuerst berücksichtigt; danach folgen die passenden Profilreferenzen. Der Adapter entfernt doppelte IDs und überträgt höchstens vier Bilder. Unterstützte Rasterbilder und SVG-Dateien werden für den Provideraufruf in größenbegrenzte PNG-Dateien umgewandelt. Bei fal.ai bleiben Referenzen auch dann erhalten, wenn die Redaktion eine eigene Bildanweisung eingibt. Ohne erreichbare Referenz schlägt ein fal.ai-Auftrag mit einer Konfigurationsmeldung fehl. Der strukturierte fal-Prompt kennzeichnet die Bilder als Stilreferenzen, nicht als zu bewahrende Szene; der tatsächlich verwendete Prompt ist im CMS einsehbar. Er ist als versionierte Codekonstante festgelegt und nicht per ENV überschreibbar.

Der fal-Adapter nutzt die persistente Provider-Queue und speichert deren Request-ID am CMS-Job. Nach einem CMS-Neustart fragt der Worker denselben externen Auftrag weiter ab. Bei Abbruch oder lokalem Timeout versucht das CMS, auch den externen Auftrag zu stornieren. Datenschutz, Vertrag, Region, Lizenzen und tatsächliche Kosten des externen Anbieters bleiben Aufgabe des Betreibers. Das CMS kann aus festen Providerpreisen oder vergleichbaren abgeschlossenen Aufträgen eine unverbindliche Kostenschätzung anzeigen; Details stehen in der Variablenreferenz.

MFLUX lokal

Auf macOS mit Apple Silicon können Sie MFLUX separat installieren und aktivieren:

uv tool install mflux --with hf_transfer

IMAGE_GENERATION_ENABLED=true
IMAGE_PROVIDER=mflux
MFLUX_IMAGE_MODEL=black-forest-labs/FLUX.2-klein-4B

Ohne ausdrückliche Bildanweisung verwendet MFLUX höchstens das bisherige Bild im Zielfeld als Ausgangspunkt. Mit Bildanweisung startet MFLUX ohne diese implizite Referenz. Globale Stilreferenzen werden diesem Adapter nicht übergeben, weil er Stil und Motiv der Referenz nicht zuverlässig trennt.

Eigener HTTP-Endpunkt

Ein kompatibler Endpunkt wird mit IMAGE_PROVIDER=http, IMAGE_HTTP_API_URL, IMAGE_HTTP_MODEL und optional IMAGE_HTTP_API_KEY konfiguriert. Der Adapter sendet model, prompt, negative_prompt, n, size und response_format=b64_json; die Antwort muss data[].b64_json oder images[].base64 enthalten. Dieser Vertrag überträgt keine Referenzbilder. Zugangsdaten bleiben ausschließlich in der Serverumgebung. Für Produktion verlangt der Adapter eine HTTPS-URL.

Vorschläge und Speicher

Die Redaktion startet jeden Bildauftrag ausdrücklich an einer angelegten Kategorie oder Story. Ein neuer Eintrag muss zunächst einmal gespeichert werden, damit er eine Dokument-ID erhält. Die Bild-Lane verarbeitet die Aufträge mit eigener Parallelität und eigenem Timeout. Offene Aufträge, Abbruch und Anbieterfehler sind im Admin-Workflow sichtbar.

Vorschläge bleiben zunächst außerhalb der Media Library. Bei S3 liegen sie unter ai-image-proposals/ im konfigurierten Medien-Bucket. Eine allgemein öffentliche Bucket-Policy muss diesen Präfix durch ein ausdrückliches Deny ausnehmen; die CMS-IAM-Identität benötigt dort Lese-, Schreib- und Löschrechte. Erst die Auswahl eines Vorschlags lädt das Bild in die Media Library. Das Einsetzen in ein Inhaltsfeld wird erst mit dem anschließenden Speichern des Eintrags dauerhaft.

Bildvorschläge sind an die erzeugende Person und die flüchtige Sitzung des geöffneten Editors gebunden. Status, Dateien und Übernahme werden nur für diese Sitzung freigegeben. Ein weiterer Auftrag für dasselbe Feld erzeugt einen eigenen Vorschlagssatz. Nach Schließen oder Neuladen des Editors sind die Sätze nicht mehr abrufbar. Nur ausdrücklich in der Media Library gespeicherte Bilder bleiben nutzbar. Nicht mehr erreichbare Vorschlagsdateien können zunächst im geschützten Speicher verbleiben; die bestehende serverseitige Bereinigung entfernt sie nach 30 Tagen. Die Job-Metadaten bleiben für die technische Auswertung erhalten.

Zugriff und Funktionsprüfung

Bild-Routen verlangen eine aktive Admin-Session und das passende Content-Manager-Recht für Story oder Kategorie: read für Status und Dateien, update für Änderungen. Verändernde Routen sind pro Route, Client-IP und CMS-Instanz begrenzt; bei mehreren Instanzen ist für ein globales Limit eine zusätzliche Begrenzung am Reverse Proxy nötig. Ein Kostenwert im Admin ist eine Schätzung, keine Rechnung und kein Budgetlimit.

Prüfen Sie nach der Einrichtung einen Auftrag für ein Icon und ein Slide-Bild: Generierung starten, Vorschläge ansehen, Alt-Text bearbeiten, genau ein Bild übernehmen und den Eintrag speichern. Kontrollieren Sie, dass nicht gewählte Vorschläge nicht in der Media Library erscheinen und der private S3-Präfix anonym nicht lesbar ist. Testen Sie außerdem den Zugriff mit einem zweiten Account und nach dem Neuladen des Editors sowie Abbruch, Fehler und fehlende Berechtigung. Der technische Ablauf steht unter KI-Jobs, TTS, Bild und Text.