fish.audio TTS (Text-to-Speech)
Erfordert FISH_AUDIO_API_KEY in .env (einen erstellen unter https://fish.audio/go-api/api-keys/).
Erstelle Sprachmodelle im fish.audio Playground und übergib deren ID als reference_id, um eine geklonte Stimme wiederzuverwenden.
Aktuelle API
Ein einzelner synchroner Aufruf, der rohe Audio-Bytes zurückgibt:
POST https://api.fish.audio/v1/tts
Authorization: Bearer ${FISH_AUDIO_API_KEY}
Content-Type: application/json
model: <Backend-Modell> # HTTP-Header wählt das Backend aus, z.B. s1
Das Backend-Modell wird mit dem model HTTP-Header ausgewählt, nicht als Feld im Body. In OpenMontage wird dies auf den model-Input des Tools abgebildet.
Backend-Modelle
model ist erforderlich – es gibt keinen Standard. Übergib eines von:
s2.1-pro— neueste Generation. Beste Qualität: Inline-Emotion-Tags, 80+ Sprachen, Multi-Speaker. Helden-Erzählung.s2.1-pro-free— kostenloser Werbe-Zugang zu s2.1-pro. Entwürfe, Samples und Validierungsläufe für 0 $ während des Aktionszeitraums. Laut der fish.audio Ankündigung: kostenlos bis zum 31. August 2026, vorbehaltlich Fair Use, keine SLA/Latenz-Garantie, Anfragen können gespeichert werden und kommerzielle Nutzung ist eingeschränkt. Leite niemals Produktions- oder Kunden-Erzählungen darüber.s2-pro— erste S2-Generation. Stabile hohe Qualität mit Emotion-Tag-Unterstützung.s1— vorheriges Flaggschiff. Zur Kompatibilität mit bestehenden Integrationen beibehalten.
Die Abrechnung erfolgt pro UTF-8-Byte des Eingabetextes (nicht pro Zeichen). CJK-Text und Emojis kosten das 3- bis 4-fache eines ASCII-Zeichens gleicher sichtbarer Länge. Aktuelle Listenpreise: s1 / s2-pro / s2.1-pro = 15 $ pro 1 Mio. Bytes, s2.1-pro-free = 0 $ nur während des Aktionszeitraums (das Tool estimate_cost() wechselt nach dem 31. August 2026 zum kostenpflichtigen s2.1-pro-Tarif). Überprüfe die aktuellen Preise unter https://docs.fish.audio/developer-guide/models-pricing/pricing-and-rate-limits vor großen Stapelverarbeitungen.
Inline-Emotion-Tags (nur S2-Modelle)
s2-pro / s2.1-pro / s2.1-pro-free interpretieren Inline-Emotion-Tags, die in den Text eingebettet sind:
- Tags wie
[laugh],[whispers]ändern die Sprechweise mitten im Satz. - Beispiel:
"Das ist ja zum Lachen [laugh] aber lassen Sie mich das ernsthaft erklären." s1interpretiert Emotion-Tags nicht – sie können als Klartext vorgelesen werden. Entferne sie daher, wenn du s1 verwendest.
Stimmauswahl (reference_id)
- Erstelle oder wähle eine Stimme im fish.audio Playground aus und kopiere dann ihre Modell-ID.
- Übergib sie als
reference_id. Der generischevoice_iddes Selektors wird als Alias akzeptiert, wennreference_idfehlt. - Ohne eine
reference_idverwendet fish.audio seine Standardstimme für das gewählte Modell.
Inline-Cloning on-the-fly (Hochladen von Referenzaudio + Text pro Anfrage) wird von diesem Tool nicht unterstützt – erstelle zuerst ein Sprachmodell im Playground.
OpenMontage Verwendung
Generiere mit dem TTS-Selektor:
from tools.audio.tts_selector import TTSSelector
result = TTSSelector().execute({
"preferred_provider": "fish_audio",
"text": "Hier ist, warum Zinseszins ruhig jeden Schnell-reich-werden-Plan schlägt.",
"model": "s1",
"reference_id": "<Playground-Sprachmodell-ID>",
"output_path": "projects/mein-video/assets/audio/erzaehlung.mp3",
})
Oder rufe den Anbieter direkt auf:
from tools.audio.fish_audio_tts import FishAudioTTS
result = FishAudioTTS().execute({
"text": "Kurze Beispielzeile zur Freigabe.",
"model": "s1",
"reference_id": "<Playground-Sprachmodell-ID>",
"output_path": "projects/mein-video/assets/audio/fish_sample.mp3",
})
Der Anbieter schreibt das Audio in den output_path und gibt data.output sowie das aufgelöste model und reference_id zurück.
Qualitäts- & Latenzoptimierung
latency:normal(Standard, beste Qualität),balanced(etwas schneller) oderlow(am schnellsten, geringer Qualitätsverlust).normalize: Standardtrue; lasse es eingeschaltet, damit Zahlen, Daten und Währungen natürlich gelesen werden.prosody: optional{ "speed": 1.0, "volume": 0 }, um Tempo/Lautstärke anzupassen.mp3_bitrate:128ist ein guter Standard; erhöhe auf192für Mischungen mit vielen Musikbetten.temperature: Standard0.7. Erhöhe auf0.9für ausdrucksstärkere Lesungen (empfohlen bei Verwendung von Emotion-Tags); niedriger für eine gleichmäßigere, vorhersehbarere Ausgabe.top_p/repetition_penalty: normalerweise bei den Standardwerten (0.7/1.2) belassen.
Empfohlener Arbeitsablauf
- Generiere ein 10-15 Sekunden langes Sample mit dem gewählten
model+reference_id, bevor du eine vollständige kostenpflichtige Erzählung erstellst. - Frage den Benutzer nach Genehmigung von Stimmnatürlichkeit, Emotion und Tempo.
- Generiere die vollständige Erzählung erst nach Genehmigung.
- Für Stapel-/Lokalisierungsvarianten, bei denen die Kosten eine Rolle spielen, prototypisiere mit
s2.1-pro-free(Aktionszeitraum 0 $; nur nicht-kommerzielle Entwürfe) und upgrade die finale Version aufs2.1-pro.
Fehlerbehebung
401 Unauthorized: falscher oder fehlenderFISH_AUDIO_API_KEY.402/ Zahlungsfehler: Kontoguthaben aufgebraucht.404/ Ungültige Stimme: Diereference_idist falsch oder gehört nicht zu diesem Konto.- Leeres/zu kurzes Audio: Prüfe, dass
textnicht leer ist undnormalizenicht die gesamte Eingabe entfernt.
Sicherheit
Gib den API-Key niemals in Logs, Metadaten, Patches oder Projektartefakten aus oder schreibe ihn dort fest. .env.example sollte nur leere Variablennamen enthalten.