Cloud-TTS-API: Audio-Generierung für Entwickler

Von KlangFaden Redaktion · Aktualisiert 2026-11-18

Diese Dokumentation erklärt, wie du die Cloud-TTS-API von KlangFaden in deine Python- oder Node.js-Anwendungen integrierst. Wir nutzen dieselbe JSON-Struktur wie die OpenAI-API, sodass du deine bestehenden Bibliotheken einfach anpassen kannst. Das Ziel ist eine zuverlässige Audio-Generierung für YouTube-Produktionen und Agenturprojekte mit hohem Volumen.

Hier findest du alle technischen Details zu den Endpunkten, verfügbaren Stimmen und den genauen Parametern für die Sprachausgabe. Erfahre, wie du lange Texte effizient verarbeitest, Rate-Limits berücksichtigst und verschiedene Audio-Formate wie MP3 oder WAV direkt abrufst. Die Beispiele sind praxisnah und auf die Bedürfnisse von Video-Produzenten zugeschnitten.

Cloud-TTS-API: Audio-Generierung für Entwickler

Häufig gestellte Fragen

Wie erhalte ich einen API-Key?

Registrieren Sie sich auf /get-api-key/ mit Google oder E-Mail. Nach dem Login sehen Sie Ihren API-Schlüssel, Ihr Guthaben und die verbleibenden Zeichen. Jeder Account pro Site erhält einen aktiven Schlüssel, den Sie jederzeit neu ausstellen können.

Welche Parameter sind für die API nötig?

Notwendig sind model (tts-1 oder tts-1-hd), input (Text bis 4096 Zeichen) und voice (einer der 8 Presets). Optional sind response_format, speed (0,25–4,0) und language. Die Authentifizierung erfolgt über den Bearer-Token im Header.

Kann ich das OpenAI SDK nutzen?

Ja, das offizielle OpenAI SDK funktioniert, indem Sie die base_url auf https://api.play9999k.com/v1 ändern und Ihren Schlüssel verwenden. Die Anfragestruktur entspricht der OpenAI-Speech-Endpunkt-Spezifikation. Andere SDKs funktionieren ebenfalls über einfaches HTTP.

Wie hoch ist das Rate-Limit?

Das Limit beträgt 60 Anfragen pro Minute pro Schlüssel. Vor der ersten Aufladung gelten 10 Anfragen pro Minute. Bei hoher Auslastung können Anfragen in einer Warteschlange verarbeitet werden. Das Limit gilt pro API-Schlüssel.

Was bedeutet tts-1-hd?

tts-1-hd ist ein Modell. Es verwendet dieselbe Engine wie tts-1. Der Preis ist für beide Modelle identisch: 10 $ pro 1 Million Zeichen.

Wie werden Fehler in der Antwort gemeldet?

Fehler werden über den HTTP-Statuscode und eine JSON-Antwort mit Fehlermeldung und Code gemeldet. Bei Synthesefehlern wird die Gebühr vollständig erstattet. Wir bieten keinen Live-Chat; Support erfolgt ausschließlich per E-Mail.

Welche Formate werden unterstützt?

Unterstützt werden mp3, wav, opus, flac und pcm. Das Format wird über den Parameter response_format im JSON-Body festgelegt. Die Audioausgabe enthält einen unsichtbaren Wasserzeichen, das die synthetische Herkunft kennzeichnet.

Kann ich die Sprache manuell setzen?

Ja, Sie können language als ISO-Code setzen. Ohne Angabe wird die Sprache aus dem Skript erraten (Latein standardmäßig Englisch). Für Nicht-Englisch-Text in Lateinschrift empfehlen wir die manuelle Einstellung, um Fehler zu vermeiden.

Wie lange sind API-Anfragen gültig?

Der API-Schlüssel bleibt aktiv, bis Sie einen neuen ausstellen. Der alte Schlüssel wird dann sofort ungültig. Die API-Anfragen selbst sind sofort gültig, sobald die Authentifizierung erfolgreich ist. Guthaben verfällt nicht.

Gibt es eine Sandbox-Umgebung?

Es gibt keine separate Sandbox-Umgebung. Sie verwenden dieselbe Produktionsumgebung mit Ihrem API-Schlüssel. Sie können Ihr kostenloses Testguthaben von 0,50 $ (ca. 50.000 Zeichen) für 7 Tage nutzen, um die API zu testen.

Wie aktualisiere ich meinen API-Key?

Sie können jederzeit einen neuen API-Schlüssel ausstellen. Der alte Schlüssel wird dann sofort ungültig. Dies geschieht über Ihre Kontoeinstellungen auf der /get-api-key/-Seite. Neue Schlüssel sind sofort einsatzbereit.

Was passiert bei Überschreitung des Limits?

Bei Überschreitung des Rate-Limits (60/min oder 10/min vor Aufladung) erhalten Sie eine Fehlermeldung. Die Anfrage wird nicht verarbeitet und nicht berechnet, wenn sie fehlschlägt. Sie können warten oder Ihr Guthaben aufladen, um das Limit zu erhöhen.

Kann ich mehrere Keys pro Konto nutzen?

Jeder Account hat nur einen aktiven Schlüssel. Sie können jedoch jederzeit einen neuen Schlüssel ausstellen, wodurch der alte sofort ungültig wird. Sie können also zwischen verschiedenen Schlüsseln wechseln, aber nicht mehrere gleichzeitig nutzen.

Wie funktioniert die Authentifizierung?

Die Authentifizierung erfolgt über den Header Authorization: Bearer tts-.... Ihr Schlüssel wird nach der Registrierung auf /get-api-key/ angezeigt. Jeder API-Aufruf muss diesen Header enthalten, um gültig zu sein.

Erste Anfrage

curl

curl https://api.play9999k.com/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.play9999k.com/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.play9999k.com/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
ariaweiblich
novaweiblich
lunaweiblich
sageweiblich
felixmännlich
milomännlich
atlasmännlich
orionmännlich
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Erste Schritte: API-Key erhalten

Schallwellenillustration für: Erste Schritte: API-Key erhalten

Um die KlangFaden API zu nutzen, registrierst du dich einfach auf der /get-api-key/ Seite. Du kannst dich entweder mit deinem Google-Konto anmelden oder ein klassisches Konto mit E-Mail und Passwort erstellen. Beide Wege führen zu einem persönlichen Konto, das direkt mit deinem API-Schlüssel verknüpft ist.

Registrierung über Google oder E-Mail

Registrierung über Google oder E-Mail

Die Registrierung ist schnell erledigt. Wenn du dich mit Google anmeldest, erhältst du sofort einen kostenlosen Testguthaben von 0,50 $. Konten, die mit E-Mail und Passwort erstellt wurden, starten ohne dieses Testguthaben. Du erhältst nach der Anmeldung Zugang zum Dashboard, um deine ersten Audio-Dateien zu generieren.

API-Key im Dashboard finden

API-Key im Dashboard finden

Nach der Anmeldung findest du deinen einzigartigen API-Schlüssel im Dashboard. Dieser Schlüssel beginnt mit "tts-" und dient als Authentifizierung für deine API-Anfragen. Du siehst hier auch deinen aktuellen Kontostand, das verbleibende Guthaben und die Anzahl der bereits generierten Zeichen.

Schlüssel bei Bedarf neu generieren

Du kannst deinen API-Schlüssel jederzeit neu generieren, falls er verloren geht oder du ihn aus Sicherheitsgründen austauschen möchtest. Der alte Schlüssel wird sofort deaktiviert, wenn du den neuen generierst.

Erste Anfrage mit cURL

Schallwellenillustration für: Erste Anfrage mit cURL

Nachdem Sie Ihren API-Schlüssel im Dashboard erhalten haben, können Sie die Audio-Generierung direkt über die Kommandozeile testen. Die Struktur der JSON-Anfrage orientiert sich an dem bekannten OpenAI-Format, was den Einstieg erheblich vereinfacht.

Senden Sie Ihre Anfrage an den Endpunkt POST https://api.play9999k.com/v1/audio/speech. Das System verarbeitet den Text und liefert im Erfolgsfall die Audiodatei als Antwort zurück.

Grundlegende JSON-Struktur

Die API erwartet ein JSON-Objekt mit den Schlüsseln model, input und voice. Das model kann entweder tts-1 oder tts-1-hd sein, wobei beide denselben Preis und Motor nutzen. Der Parameter input enthält den zu sprechenden Text (max. 4096 Zeichen).

Optional können Sie response_format (z. B. mp3, wav, opus, flac, pcm) und speed (0.25–4.0) anpassen. Für die Authentifizierung wird der Header Authorization: Bearer <Ihr-Schlüssel> benötigt.

Parameter für Text und Stimme

Wählen Sie eine der 8 verfügbaren Stimmen, wie etwa aria für klare Erzählungen oder atlas für neutrale Nachrichten. Der Text wird direkt im input-Feld übergeben. Achten Sie darauf, dass lange Texte die 4096-Zeichen-Grenze nicht überschreiten.

Das Feld language ist optional. Wird es nicht gesetzt, wird die Sprache basierend auf dem Skript erraten. Für lateinische Texte außerhalb des Englischen empfehlen wir, language explizit zu setzen, um falsche Zuordnungen zu vermeiden.

Erhalten der Audio-Datei

Nach erfolgreicher Verarbeitung erhalten Sie die Audiodatei direkt in der Antwort. Die Generierung dauert bei kurzen Phrasen nur wenige Sekunden. Bei hoher Auslastung kann es zu Warteschlangen kommen, da Anfragen sequenziell bearbeitet werden.

Bei fehlgeschlagenen Anfragen erhalten Sie den vollen Betrag zurückerstattet. Die Antwort enthält die Audiodaten im gewählten Format, die Sie direkt speichern oder weiterverarbeiten können.

Nutzung mit dem OpenAI SDK

Schallwellenillustration für: Nutzung mit dem OpenAI SDK

Die Integration von KlangFaden in bestehende Workflows ist dank der Kompatibilität mit OpenAI-Standard-SDKs denkbar einfach. Da die API dieselbe JSON-Struktur und dieselbe Anfrageform verwendet, müssen Sie nur die base_url Ihres SDKs anpassen. Dies ermöglicht die direkte Nutzung der offiziellen Python- und Node.js-Clientbibliotheken.

Durch die Änderung der Basis-URL auf https://api.play9999k.com/v1 und die Übergabe Ihres API-Schlüssels im Authorization-Header nutzen Sie dieselbe Architektur wie bei OpenAI. Dies vereinfacht das Testing und die Migration erheblich, da Entwickler bereits mit der Struktur vertraut sind. Die Authentifizierung erfolgt weiterhin über den Bearer-Token, den Sie in Ihrem Dashboard erhalten.

Anpassen der base_url

Um die KlangFaden-API mit OpenAI-SDKs zu nutzen, ändern Sie die Konfigurationsvariable base_url von https://api.openai.com/v1 auf https://api.play9999k.com/v1. Dies ist der einzige notwendige Schritt, um den Endpunkt für die Audio-Generierung umzuleiten.

Stellen Sie sicher, dass Sie Ihren individuellen API-Schlüssel (Start mit tts-...) im Header Authorization: Bearer <IHR_SCHLÜSSEL> übergeben. Die restlichen Request-Parameter bleiben identisch mit der Standard-Sprachsynthese-API.

Verwendung der offiziellen SDKs

Da die Anfrageformate übereinstimmen, funktionieren die offiziellen OpenAI-SDKs für Python und Node.js nahtlos. Sie benötigen keine proprietären Bibliotheken, sondern nutzen die bewährten, gut dokumentierten Client-Bibliotheken, die bereits in vielen Projekten vorhanden sind.

Dies spart Entwicklungszeit, da Sie keine neuen Integrationsmuster erlernen müssen. Die Fehlerbehandlung und Response-Struktur bleibt durch die Kompatibilität vorhersehbar und stabil.

Beispielcode für Python/Node.js

In Python können Sie die openai-Bibliothek importieren und die Base-URL überschreiben. Im Node.js-Setzen Sie die BASE_URL-Umgebungsvariable oder konfigurieren Sie den Client entsprechend. Beide Umgebungen unterstützen die direkte Übergabe von Text und Stimulus-Parametern.

Die Antwort enthält die Audiodaten im gewählten Format, die Sie direkt speichern oder weiterverarbeiten können. Dies ermöglicht eine schnelle Automatisierung von Video-Inhalten ohne zusätzliche Middleware.

Stellen Sie sicher, dass Ihr SDK die neueste Version verwendet, um alle neuen Parameter wie language korrekt zu unterstützen. Die Geschwindigkeitseinstellungen (speed) und Formatwahlen (response_format) funktionieren wie gewohnt.

  • Importieren Sie die Standard-OpenAI-Bibliothek
  • Setzen Sie base_url='https://api.play9999k.com/v1'
  • Verwenden Sie client.audio.speech.create()
  • Übergabe des API-Schlüssels im Header

Verfügbare Endpunkte

Schallwellenillustration für: Verfügbare Endpunkte

Die API kommuniziert über klare REST-Endpunkte. Das POST-Endpunkt verarbeitet Texteingaben und generiert Audio, während die GET-Endpunkte Metadaten zu Stimmen und Modellen bereitstellen. Diese Struktur ermöglicht eine einfache Integration in bestehende Workflows von YouTube-Erstellern und Agenturen.

POST /v1/audio/speech für Audio

Dieser Endpunkt wandelt Text in Audio um. Sie senden eine JSON-Anfrage mit Modell, Eingabetext und Stimme. Die Antwort enthält die Audiodatei im gewünschten Format.

  • POST https://api.play9999k.com/v1/audio/speech
  • Akzeptiert JSON-Body mit Text und Parametern
  • Gibt die Audiodatei zurück

GET /v1/voices für Stimm-Infos

Rufen Sie verfügbare Stimmen und deren Eigenschaften ab. Dieser Endpunkt listet alle 8 Stimmen-Presets sowie unterstützte Sprachen und Formate auf. Ideal zur dynamischen Auswahl in Ihrer Benutzeroberfläche.

  • GET https://api.play9999k.com/v1/voices
  • Listet Stimmen, Sprachen und Formate auf
  • Zeigt verfügbare Stimmen, Sprachen und Formate

GET /v1/models für Modellauswahl

Ermitteln Sie die verfügbaren Modelle. Aktuell stehen tts-1 und tts-1-hd zur Verfügung. Beide nutzen dieselbe Engine und denselben Preis. Dieser Endpunkt hilft bei der korrekten Konfiguration Ihrer Requests.

  • GET https://api.play9999k.com/v1/models
  • Zeigt tts-1 und tts-1-hd an
  • Dient zur Validierung der Modellauswahl

Parameter und Einstellungen

Schallwellenillustration für: Parameter und Einstellungen

Die API bietet zwei Modelle: tts-1 und tts-1-hd. Beide nutzen dieselbe Engine und haben denselben Preis. Die Wahl zwischen ihnen ändert nichts an den Kosten.

Modell-Auswahl: tts-1 und tts-1-hd

Setze das Feld model auf entweder tts-1 oder tts-1-hd. Da beide dieselbe Engine verwenden, ist die Entscheidung rein formaler Natur. Der Preis beträgt konstant 0,01 $ pro 1.000 Zeichen, unabhängig vom Modell-String.

Sprach-Codes und Automatik

Das Feld language ist optional. Wenn es nicht gesetzt ist, versucht die API, die Sprache automatisch zu erkennen. Bei lateinischem Text wird standardmäßig Englisch vorausgesetzt. Für andere Sprachen wie Deutsch, Spanisch oder Französisch solltest du den ISO-Code explizit setzen, um Fehler zu vermeiden.

  • Unterstützte Sprachen: Arabisch, Chinesisch, Dänisch, Deutsch, Englisch, Finnisch, Französisch, Griechisch, Hebräisch, Hindi, Italienisch, Japanisch, Koreanisch, Malaysisch, Norwegisch, Polnisch, Portugiesisch, Russisch, Spanisch, Swahili, Schwedisch, Türkisch, Niederländisch, Isländisch.

Geschwindigkeitsbereich anpassen

Mit dem Parameter speed steuerst du die Abspielgeschwindigkeit im Bereich von 0,25 bis 4,0. Der Standardwert ist 1,0. Ändere diesen Wert, um die Stimme schneller oder langsamer klingen zu lassen, ohne die Pitch zu verändern.

Parameter und Einstellungen

Fehlerbehandlung und Limits

Schallwellenillustration für: Fehlerbehandlung und Limits

Die API verarbeitet Anfragen nacheinander, weshalb sie bei hoher Last in eine Warteschlange eintreten kann. Dies führt dazu, dass kurze Sätze einige Sekunden benötigen und längere Texte in etwa Echtzeit (ca. 25 Zeichen pro Sekunde) generiert werden. Die Geschwindigkeit variiert je nach Auslastung des Systems.

Jeder API-Schlüssel ist auf 60 Anfragen pro Minute begrenzt. Vor der ersten Aufladung des Kontos gelten strengere 10 Anfragen pro Minute. Diese Limits gelten pro Schlüssel und werden serverseitig überwacht, um eine stabile Leistung für alle Nutzer zu gewährleisten.

Rate-Limits: 60 Anfragen pro Minute

Standardmäßig sind 60 erfolgreiche Anfragen pro Minute pro API-Schlüssel erlaubt. Bei neuen Konten ohne Guthaben liegt das Limit bei 10 Anfragen pro Minute. Sobald ein Top-up erfolgt, gilt das Standardlimit sofort wieder.

Umgang mit Warteschlangen

Bei hoher Auslastung werden Anfragen sequenziell verarbeitet. Dies kann zu kurzen Verzögerungen führen, insbesondere bei komplexeren Modellen oder langen Texten. Wir empfehlen, Requests nicht zu parallelisieren, um Wartezeiten zu minimieren.

Fehlercodes und Bedeutungen

Bei einem Synthese-Fehler erhalten Sie eine Rückmeldung ohne Kosten. Fehlercodes wie 429 (Rate Limit) oder 400 (ungültiger Text) informieren über das Problem. Bei 429 warten Sie einfach kurz auf, bis das Limit wieder frei ist.

  • 400: Ungültiger Eingabetext oder Format
  • 401: Falscher oder abgelaufener API-Key
  • 429: Rate Limit überschritten
  • 500: Interner Serverfehler (selten)

Audio-Formate und Ausgabe

Schallwellenillustration für: Audio-Formate und Ausgabe

Wähle das Ausgabeformat über das Feld response_format in deiner API-Anfrage. Wir unterstützen MP3, WAV, OPUS, FLAC und PCM, um den Speicherbedarf und die Qualität an deine Anforderungen anzupassen.

Unterstützung für MP3, WAV, OPUS

MP3 ist die effiziente Standardwahl für Web- und Video-Produktionen. WAV und OPUS bieten verlustfreie bzw. hochwertige Alternativen für die weitere Bearbeitung in professionellen Workflows.

FLAC und PCM für hohe Qualität

Für maximale Audioqualität ohne Kompressionsverluste stehen FLAC und PCM zur Verfügung. Dies ist ideal, wenn du die Audiodateien später in deiner Postproduktion weiterverarbeitest.

Wiedergabe der Audio-Dateien

Die generierten Audio-Dateien werden direkt im Response zurückgegeben. Du kannst sie sofort speichern oder weiterverwenden. Jede Datei enthält einen unsichtbaren Wasserzeichen, das die synthetische Herkunft kennzeichnet.

Best Practices für Agenturen

Schallwellenillustration für: Best Practices für Agenturen

Agenturen, die große Textmengen für YouTube-Produktionen verarbeiten, müssen die Rate-Limits von 60 Anfragen pro Minute effizient nutzen. Da Anfragen sequentiell verarbeitet werden, kann es bei hoher Last zu Warteschlangen kommen. Parallelisierung mehrerer API-Keys oder Anfragen ist ratsam, um Engpässe zu vermeiden.

Parallelisierung von Anfragen

Nutzen Sie mehrere API-Keys parallel, um den Durchsatz zu erhöhen. Da jeder Key auf 60 Anfragen pro Minute begrenzt ist, ermöglicht dies eine höhere Gesamtleistung. Achten Sie darauf, Anfragen nicht zu stauen, da sie nacheinander bearbeitet werden.

Behandlung langer Texte

Teilen Sie Texte in Abschnitte von maximal 4096 Zeichen auf. Generieren Sie für jeden Abschnitt eine eigene Audio-Datei und fügen Sie diese im Nachhinein zusammen. Dies verhindert Fehler bei langen Eingaben und erleichtert die Fehlerbehebung.

Caching von Audio-Dateien

Speichern Sie generierte Audio-Dateien lokal oder in Ihrem CDN, wenn der Text unverändert bleibt. Da die Generierung etwa Echtzeit-Geschwindigkeit hat, spart Caching sowohl Zeit als auch Kosten. Wiederholte Anfragen für denselben Text müssen nicht erneut verarbeitet werden.

Hören Sie sich die 8 Stimmen an

Jede der folgenden Samples wurde von dieser API aus demselben Satz generiert. Luna eignet sich sanft für Storytelling-Formate, während Sage mit ihrer ruhigen, instruktiven Art perfekt für E-Learning oder Tutorials ist.

Avatar der Stimme aria
ariaweiblich
Avatar der Stimme nova
novaweiblich
Avatar der Stimme luna
lunaweiblich
Avatar der Stimme sage
sageweiblich
Avatar der Stimme felix
felixmännlich
Avatar der Stimme milo
milomännlich
Avatar der Stimme atlas
atlasmännlich
Avatar der Stimme orion
orionmännlich

23 Sprachen

Jede Stimme kann jede dieser Sprachen sprechen.

Quellen und weiterführende Literatur

  1. Wikipedia
  2. LibriTTS-R paper (arXiv 2305.18802)
  3. LibriTTS-R corpus (OpenSLR 141)
  4. MDN: Web Speech API
  5. ISO 639 language codes
  6. curl documentation
  7. TRON developer hub: TRC-20
  8. W3C WAI: making audio and video accessible
  9. OpenAI API reference: create speech
  10. Creative Commons Attribution 4.0
  11. LibriVox public-domain audiobooks
  12. Python documentation

Mehr auf dieser Website