Direkt zum Hauptinhalt

AI Image Generation

Chatlix kann auf Knopfdruck Bilder mit gpt-image-1 (OpenAI) generieren. Klassisch als Reward-Reaktion gedacht: Zuschauer löst einen Twitch-Reward ein → Chatlix generiert ein Bild aus dem Prompt → Overlay zeigt es kurz an. Genauso nutzbar manuell im Pack-Editor/der Mediathek.

Kosten — gestaffelt nach Qualität und Größe

Korrektur gegenüber älteren Angaben: Es gibt keinen einzelnen Flat-Preis mehr, sondern eine Staffel (Margen-Fix Juni 2026, Quelle AiCreditsService::COST_MULTIPLIER):

  • Low-Qualität, 1024×1024: 8 Credits (Action-Key ai.image.generate.low).
  • Medium-Qualität, 1024×1024 (Default, wenn du nichts angibst): 15 Credits (ai.image.generate).
  • High-Qualität oder jede 1536er-Größe (1024×1536 / 1536×1024): 20 Credits (ai.image.generate.high) — unabhängig davon, welche Qualität du anfragst. Grund: OpenAI berechnet 1536er-Formate intern wie „high" (~0,15 €), daher wird das auch bei angefragter „low"/„medium"-Qualität als High-Tier verrechnet, damit die Marge stimmt.

Erlaubte Größen: 1024x1024 (Default), 1024x1536, 1536x1024. Alles andere wird serverseitig auf den Default zurückgesetzt. Erlaubte Qualitäten: low, medium (Default), high — auch hier wird ein ungültiger Wert stillschweigend auf medium zurückgesetzt.

Belastet wird nach erfolgreichem Provider-Call. Bei Provider-Fehler oder wenn das Bild nicht ins Media-System übernommen werden kann, wird die Belastung automatisch refunded (Ledger-Grund ai.image.generate[.low|.high]_provider_failed bzw. _media_failed) — es fällt effektiv keine Buchung an.

Limits, die es sonst nirgends dokumentiert gibt

  • Prompt-Länge: maximal 2.000 Zeichen. Darüber: prompt_too_long, ohne Charge.
  • Gratis-Tageskontingent (Korrektur): Ein kostenloses Tages-Kontingent (UTC-Grenze, unabhängig vom Credit-Kontingent) ist im Code aktuell nur für den Starter-Plan hinterlegt, mit 1 Bild/Tag — nicht für den Free-Plan, und nicht 2/Tag. Free-Plan sowie Creator/Pro Max/Team haben hierfür den Wert 0 konfiguriert, bekommen also gar kein separates Gratis-Kontingent; dort kostet jedes Bild normal Credits. Bei Erreichen des Starter-Limits kommt free_ai_daily_limit zurück — die im Code hinterlegte Hinweis-Meldung sagt trotzdem wörtlich „Du hast deine 2 AI-Bilder für heute schon erzeugt." (Text-Altlast, tatsächlicher Grenzwert ist 1).
  • Anti-Spam-Cooldown: 5 Sekunden pro User zwischen zwei Bild-Generierungen (Redis-Lock, additiv zum Cooldown deiner Automation-Regel). Greift der Cooldown, kommt cooldown_active zurück — ohne Charge, es wird also kein Credit für Spam-Versuche verbrannt.
  • Retry-Verhalten: bei transienten Fehlern (5xx, Timeout, Connection-Reset) macht der Provider genau einen Retry mit kurzer Pause. Bei 4xx (Content-Policy, ungültiger Prompt, Billing-Hard-Stop) gibt es keinen Retry, um keine doppelten API-Kosten zu riskieren.
  • Provider-Timeout: 30 Sekunden Curl-Timeout pro Versuch (üblich sind 5–15s für gpt-image-1).

Manuelle Generierung im Dashboard

Dashboard → Pack-Editor/Mediathek → AI-Bild generieren (Endpoint /v1/creator/ai-image/generate, sitzungsbasiert mit CSRF-Schutz).

  1. Prompt eingeben (z. B. Pixel-Art-Drache mit Twitch-Logo). Optional: Style-Feld (wird als „— Style: ..." an den Prompt angehängt) und Negativ-Prompt (wird als „— Vermeide: ..." angehängt, siehe unten).
  2. « Generieren ». Wartezeit typischerweise 5–15 Sekunden.
  3. Ergebnis wird angezeigt. Buttons: « Speichern » (legt es im Media-Bereich ab, Dateiname-Präfix ai-), « Im Overlay zeigen », « Verwerfen ».

Gespeicherte Bilder landen im normalen Media-Storage und können wie jede andere Datei in Overlays, Alerts oder Stream-Memory verwendet werden. Sie zählen gegen das Speicher-Kontingent deines Plans.

Als Reward-Reaktion (Twitch)

Das typische Setup läuft über den separaten Worker-Endpoint(kein Session-Auth, sondern Channel-Owner-Lookup über bot_instances):

  1. Twitch-Reward anlegen oder existierenden auswählen (Dashboard → Twitch → Rewards).
  2. Automation-Regel: Trigger = twitch.reward.redeemed, Filter = dein Reward.
  3. Aktion = « AI-Bild generieren ».
  4. Prompt-Template: z. B. {user_input_or_user_message}. Der Zuschauer-Text aus dem Reward landet als Prompt (Limit weiterhin 2.000 Zeichen).
  5. Aktion = « Overlay zeigen ». Eingabe = generiertes Bild. Anzeigedauer z. B. 6–10 Sekunden.

Wichtig: setze einen Cost auf den Reward, der mindestens den Credit-Wert deckt — je nach Qualität/Größe 8, 15 oder 20 Credits. Bei einem Standard-Reward mit medium/1024er (15 Credits) muss der Twitch-Cost wirtschaftlich für dich passen, sonst nutzt jemand das als Spam-Reward. Der 5-Sekunden-Cooldown schützt zusätzlich gegen Doppel-Einlösungen in kurzer Folge, ersetzt aber keine sinnvolle Reward-Kalkulation.

Prompt-Hygiene

  • Kürze hilft. Modelle sind besser im Verstehen kurzer, klarer Prompts als langer Beschreibungen.
  • Stil-Hinweis: über das separate style-Feld mitgeben, nicht in den Haupt-Prompt schreiben — Chatlix hängt es serverseitig sauber als „— Style: ..." an (max. 200 Zeichen).
  • Negativ-Prompts werden unterstützt — das war in der alten Doku falsch. Über das negative_prompt-Feld (max. 1.000 Zeichen) wird der Text als „— Vermeide: ..." an den eigentlichen Prompt angehängt, bevor er an gpt-image-1 geht. Es ist kein natives Negative-Prompt-Feature der OpenAI-API (die kennt so etwas tatsächlich nicht), sondern ein Chatlix-seitiger Textbaustein-Trick — funktioniert in der Praxis, ist aber weniger zuverlässig als ein echtes Negative-Prompting bei Stable-Diffusion-artigen Modellen.

Inhaltliche Filter

Provider-seitig läuft eine Content-Policy. Verstoßende Prompts kommen mit:

{"ok": false, "code": "provider_failed", "detail": "openai_4xx_400:content_policy_violation"}

zurück, ohne Credit-Abzug (automatischer Refund). Wenn dein Channel ein Publikum hat, das gern an die Grenzen geht: kombiniere die Reward-Aktion mit einer Pre-Filter-Liste (Dashboard → Automation → Filter „Wort-Blocklist"), um offensichtliche Trigger-Wörter abzufangen, bevor sie überhaupt an OpenAI gehen.

Stub-Modus für Tests

Wenn du eine Reward-Regel testen willst, ohne echte Bilder zu generieren und ohne Credits zu verbrennen: Provider-Parameter auf stub setzen (intern über StubImageProvider). Läuft automatisch auch als Fallback, wenn kein OpenAI-Key konfiguriert ist. Der Endpoint liefert dann ein deterministisches Test-Bild zurück, ohne OpenAI zu kontaktieren und ohne Credits zu buchen. Praktisch um Overlay-Layout, Alert-Sound und Timing zu testen.

Fehler-Verhalten und HTTP-Status

Anders als beim TTS/SFX-Feature (siehe Seite TTS einrichten) laufen die meisten fachlichen Fehler hier bewusst über HTTP 200 + ok:false, damit der Worker bei einem automatischen Retry nicht denselben kostenpflichtigen OpenAI-Call mehrfach auslöst:

  • cooldown_active, provider_failed (Content-Policy-Ablehnungen kommen hierüber, im detail-Feld), media_insert_failed, free_ai_daily_limit → HTTP 200.
  • insufficient_credits → einzige Ausnahme, kommt als HTTP 402 zurück.
  • prompt_required, prompt_too_long, provider_not_allowed → werden serverseitig meist schon vor dem Charge abgefangen, ebenfalls ohne Credit-Verbrauch.

Reward bleibt in Twitch bei einem Fehlschlag als „eingelöst" stehen — du kannst ihn manuell refunden oder die Automation-Regel um eine Fallback-Aktion ergänzen (z. B. „statt Bild eine Text-Antwort posten").

Bekannte Grenzen

  • Bilder werden nicht „verbessert", wenn du sie nochmal generierst — gpt-image-1 ist nicht deterministisch.
  • Keine Bild-zu-Bild-Funktion in Chatlix. Nur Text-zu-Bild.
  • Maximale Anzeige-Dauer im Overlay ist nicht technisch limitiert, aber lange Anzeigen blockieren weitere Alert-Bilder in der Queue. Empfehlung: 6–10 Sekunden.
  • Bilder werden im Media-Storage gespeichert und zählen gegen das Speicher-Kontingent deines Plans.
  • Größen jenseits von 1024x1024/1024x1536/1536x1024 werden nicht abgelehnt, sondern stillschweigend auf 1024x1024 zurückgesetzt — falls dein generiertes Bild nicht das erwartete Seitenverhältnis hat, das zuerst prüfen.

AI-Bild-Action intern (für Entwickler)

Die Action lebt in Chatlix\Service\AiImageService (Orchestrierung: Charge → Provider-Call → MediaService::insertImageFromBuffer → Refund bei Fehler), der eigentliche API-Call in Chatlix\Ai\Image\OpenAIImageProvider. Die Action ist additiv zu MediaService (Storage) und der Alert-Pipeline (Overlay-Push) — sie ersetzt nichts, sondern hängt sich davor. Zwei separate Routen im Code: der Worker-Pfad(Channel-Owner-Lookup, kein Session-Auth) und der Creator-Pfad /v1/creator/ai-image/generate (Session + CSRF) — beide rufen denselben Service auf.

Siehe auch

  • AI Features Überblick — Credits-System, Pakete, Fehler-Verhalten im Gesamtüberblick.
  • TTS einrichten — für den Audio-Pfad mit abweichendem HTTP-Fehlerverhalten.