TTS einrichten

Text-to-Speech (TTS) lässt Texte über eine ausgewählte Stimme sprechen — als Automation-Aktion (speak_text), als eigenständige Generierung im Audio Studio, oder als Preview im Voices-Dashboard. Chatlix nutzt ElevenLabs als Provider. Abgerechnet wird über Credits — aber pauschal pro Call, nicht pro Zeichen (dazu unten mehr, das war in der alten Doku falsch dargestellt).

Voraussetzungen

Aktiver Plan mit AI-Kontingent oder gekaufte Zukauf-Credits — oder ein eigener ElevenLabs-Key im BYO-Modus (siehe unten, dann werden gar keine Chatlix-Credits verbraucht).
Mindestens eine TTS-Stimme ausgewählt (siehe unten).
Ein Output-Ziel — Overlay-Browserquelle, Alert-Channel, oder direkte Nutzung im Audio Studio.

Stimme auswählen

Dashboard → /dashboard/voices.

Liste der verfügbaren Stimmen durchsehen. Die Liste kombiniert drei Quellen: global kuratierte Presets, dein Per-User-ElevenLabs-Cache (wenn du eigene Stimmen bei ElevenLabs geklont/ausgewählt hast) und — falls im shared_demo-Modus und noch kein Cache vorhanden ist — einen Demo-Fallback-Satz.
« Probe anhören » spielt ein vorgerendertes Demo-Sample — kostenlos, unabhängig vom Credit-Kontingent.
« Auswählen » setzt die Stimme als Standard für neue TTS-Aktionen.

Du kannst mehrere Stimmen gleichzeitig „aktiv" haben und pro Automation-Regel eine andere wählen. Achtung Kosten-Detail: Manche Stimmen sind als „Premium" markiert und tragen einen Credit-Multiplikator (Faktor > 1.00) auf den Basispreis — das ist providerseitig durch höhere ElevenLabs-Kosten für bestimmte Voice-Kategorien begründet. Der effektive Multiplikator für eine Stimme steht in der Voice-Liste im Dashboard neben dem Namen.

Eigener ElevenLabs-Key (BYO) statt Chatlix-Credits

Im Voices-Dashboard kannst du zwischen drei Modi wählen:

chatlix_key (Default, intern shared_demo) — Chatlix stellt den ElevenLabs-Zugang, jede Operation kostet Credits aus deinem Kontingent.
byo_key (intern user_key) — du hinterlegst deinen eigenen ElevenLabs-API-Key. Alle TTS-/SFX-Calls laufen dann direkt über deinen Account, ohne Chatlix-Credits zu verbrauchen. Du wirst ausschließlich von ElevenLabs abgerechnet. Fehlt der Key trotz aktiviertem BYO-Modus, wird jede Operation mit byo_key_missing blockiert — es gibt keinen automatischen Rückfall auf den Chatlix-Key.
disabled — TTS/SFX komplett deaktiviert für den Account.

BYO lohnt sich vor allem bei sehr hohem TTS-Volumen (z. B. Dauer-Vorlese-Bots), weil du dann direkt zu ElevenLabs-Konditionen zahlst statt über die Chatlix-Credit-Staffel.

TTS in einer Automation-Regel verwenden

Dashboard → Automation → Regel bearbeiten → Aktion hinzufügen → « TTS abspielen » (intern Action-Key speak_text).

Felder:

Text: was gesprochen werden soll. Variablen wie {user}, {message} werden ersetzt.
Voice: Dropdown der ausgewählten Stimmen.
Output: Overlay (an OBS-Browserquelle) oder direkter Audio-Stream.

Achtung: Die Längenprüfung läuft nach dem Einsetzen der Variablen, auf dem final gerenderten Text. Ein Chat-Input mit sehr langem Inhalt kann also text_too_long_after_render auslösen, obwohl dein Template kurz ist. Empfehlung: Eingaben clampen, z. B. mit einer Truncate-Variable, bevor sie in den TTS-Text eingesetzt werden.

Längenlimits — drei verschiedene Werte, je nach Weg

Es gibt nicht ein globales TTS-Limit, sondern drei unterschiedliche Caps je nach Aufrufpfad (Quelle: AudioGenerationService-Konstanten und AudioActionService::SPEAK_TEXT_RENDERED_MAX):

Automation-Aktion speak_text (gerenderter Text nach Variablen-Ersetzung): 500 Zeichen. Überschreitung → text_too_long_after_render.
Manuelle Generierung im Audio Studio: 1.500 Zeichen. Überschreitung → text_too_long, HTTP 400.
Preview/Test-Sample im Dashboard: 300 Zeichen (kostet dafür nur 1 Credit statt 5).

Die Prüfung passiert vor dem Provider-Call. Bei Überschreitung: kein Credit-Verbrauch, kein Provider-Call, kein „halb gesprochener" Text — entweder komplett oder klar abgelehnt.

Kosten verstehen

Wichtige Korrektur gegenüber älteren Angaben: TTS wird nicht pro Zeichen abgerechnet, sondern pauschal pro Call:

Normale TTS-Generierung (ai.tts): 5 Credits pro Call — egal ob der Text 20 oder 500 Zeichen hat (innerhalb des jeweiligen Limits).
Preview/Test-Sample (ai.tts_test): 1 Credit pro Call, max. 300 Zeichen.
Premium-Stimmen können einen zusätzlichen Multiplikator auf diesen Basispreis haben (siehe oben, Voice-Liste im Dashboard zeigt den konkreten Wert).
Ein Cache-Hit (identischer Text + identische Stimme + identische Einstellungen wurde schon einmal generiert) kostet 0 Credits — es wird das gecachte Audio ausgeliefert, kein neuer Provider-Call.

Die Buchung passiert nach erfolgreichem Provider-Call. Schlägt der Call fehl (Provider-Fehler, Storage-Fehler), wird automatisch refunded (Ledger-Grund ai.tts_failed_refund bzw. ai.tts_storage_failed_refund).

Provider-Fehler und Limits

auth_failed (HTTP 401) — der hinterlegte ElevenLabs-Key wird abgelehnt. Key prüfen/neu eintragen.
rate_limited (HTTP 429) / server_error (HTTP 502) — ElevenLabs antwortet mit Rate-Limit bzw. Serverfehler. Kein Credit-Abzug (automatischer Refund, falls schon gecharged).
voice_id_invalid / not_found — die ausgewählte Stimme ist ungültig oder wurde providerseitig entfernt. Andere Stimme wählen.
insufficient_credits — Kontingent leer. /dashboard/ai-credits öffnen.
audio_limit_reached — ein Rate-/Kontingent-Limit aus ElevenLabsProviderService::canGenerateTts() greift (z. B. tägliches/monatliches Volumen). Kommt als HTTP 429.
byo_key_missing — BYO-Modus aktiv, aber kein Key hinterlegt.

Wichtig zum HTTP-Status: Anders als beim AI-Bild-Feature laufen TTS/SFX-Fehler nicht pauschal über HTTP 200. Der Audio-Studio-Endpoint sendet den tatsächlichen Statuscode aus der Service-Antwort weiter: 400 für Längen-/Validierungsfehler, 429 für Rate-Limits, 402-artige Fälle für Credit-Themen. Ein Client muss also den HTTP-Status auswerten, nicht nur ok:false im Body.

Kurzer Blick auf SFX (Audio Studio)

Neben TTS bietet der ElevenLabs-Sound-Effects-Endpoint auch reine Sound-Effekt-Generierung (kein gesprochener Text, sondern z. B. „Explosion, cartoonig" als Prompt). Prompt-Limit 1.000 Zeichen, Kosten 5 Credits (ai.sfx) bzw. 1 Credit für die Preview (ai.sfx_test, Ergebnis wird dabei verworfen und nicht gespeichert). Max. Effektlänge 10 Sekunden. Zu finden unter /dashboard/audio-studio.

Voice-Service intern (für Entwickler)

Relevante Klassen: Chatlix\Service\Voice\AudioGenerationService (Orchestrierung, Caps, Charge/Refund), Chatlix\Service\Voice\AudioActionService (Automation-Aktion speak_text, 500-Zeichen-Cap), Chatlix\Service\Voice\VoiceCatalogService (Voice-Liste, Multiplikator-Auflösung), Chatlix\Service\Voice\ElevenLabsProviderService (Mode-Resolution chatlix_key/byo_key/disabled, Rate-Limits). Fachliche Fehler beim AI-Bild-Feature laufen bewusst über 200+ok:false, damit ein Retry im Worker nicht denselben kostenpflichtigen Call mehrfach auslöst — beim TTS/SFX-Pfad ist das Verhalten wie oben beschrieben anders, weil hier der Dashboard-Client direkt antwortet und keinen Auto-Retry-Loop hat.

Häufige Probleme

Stille im Overlay — Browserquelle in OBS muss „Audio steuert über OBS" aktiv haben. Sonst spielt der Sound zwar im Browser, OBS leitet ihn aber nicht weiter.
Knackgeräusch am Anfang — Sample-Rate des Output-Geräts auf 48 kHz fixieren.
TTS doppelt gespielt — du hast die Aktion zweimal in derselben Regel. Dashboard → Regel → Aktionen prüfen.
Unerwartetes text_too_long_after_render bei kurzem Template — die Variablen-Ersetzung hat den Text aufgebläht (z. B. sehr langer Chat-Input in {message}). Truncate-Variable einbauen oder Input-Länge vorher begrenzen.
BYO-Key funktioniert nicht — prüfen ob der Modus wirklich auf byo_key steht und der Key im Voices-Dashboard hinterlegt ist. Ohne Key blockiert die Operation komplett (byo_key_missing), es gibt keinen Fallback.

Siehe auch

AI Features Überblick — Credits-System, Pakete, Fehler-Verhalten im Gesamtüberblick.
AI Image Generation — für den Bild-Pfad, der sich beim Fehler-Verhalten (HTTP-Status) deutlich anders verhält als TTS/SFX.