Häufig gestellte Fragen
Wie erhalte ich einen API-Key?
Registrieren Sie sich auf /get-api-key/ mit Google oder E-Mail. Nach der Anmeldung wird der API-Key auf dem Dashboard angezeigt. Pro Konto ist jeweils nur ein aktiver Schlüssel gültig. Ein neuer Schlüssel kann jederzeit ausgestellt werden, wobei der alte sofort deaktiviert wird.
Welche Parameter sind für die Anfrage erforderlich?
Erforderlich sind die Felder model (z. B. tts-1) und input (der Text, maximal 4096 Zeichen). voice ist optional. Optional sind response_format, speed und language. Die Authentifizierung erfolgt über den Bearer-Token im Header.
Kann ich die OpenAI SDK verwenden?
Ja, die offiziellen OpenAI SDKs funktionieren, da die Anfragestruktur identisch ist. Sie müssen lediglich die base_url auf https://api.playnb66.com/v1 ändern und Ihren API-Schlüssel verwenden. Dies ermöglicht eine nahtlose Integration in bestehende Code-Basen, die bereits auf OpenAI setzen.
Wie ändere ich die Base URL?
Ändern Sie die Base URL in Ihrer Konfiguration auf https://api.playnb66.com/v1. Dies ist notwendig, damit Ihre Anfragen an unseren Endpunkt für die Text-zu-Sprache-Erzeugung gesendet werden. Die Struktur der JSON-Anfrage bleibt dabei unverändert zur Standard-API.
Welche Formate werden unterstützt?
Sie können zwischen mp3, wav, opus, flac und pcm wählen. Die Wahl des Formats hängt von Ihren Speicher- und Wiedergabebedürfnissen ab. Alle Formate werden direkt im Antwortkörper der API als Audiodaten zurückgegeben.
Wie funktioniert die Authentifizierung?
Die Authentifizierung erfolgt über den HTTP-Header Authorization: Bearer tts-.... Sie verwenden Ihren persönlichen API-Schlüssel, den Sie nach der Registrierung auf der Dashboard-Seite erhalten. Jeder Anfrage muss dieser Header hinzugefügt werden, um die Identität und das Kontingent zu verifizieren.
Was bedeutet 'tts-1-hd'?
tts-1-hd ist das Modell für hochwertige Audioausgabe. Es verwendet denselben Motor wie tts-1, bietet aber eine höhere Qualität. Der Preis ist identisch. Die Wahl des Modells erfolgt über das Feld model in der JSON-Anfrage an den Endpunkt.
Wie lange dauert eine Antwort?
Die Generierung dauert bei langen Texten etwa Echtzeit (25 Zeichen pro Sekunde). Kurze Sätze benötigen einige Sekunden. Anfragen werden nacheinander verarbeitet, sodass es bei hoher Last zu Wartezeiten in der Queue kommen kann. Die Antwort ist eine Audiodatei.
Was passiert, wenn das Limit erreicht ist?
Das Limit beträgt 60 Anfragen pro Minute pro Schlüssel. Vor der ersten Aufladung gelten 10 Anfragen pro Minute. Wenn das Limit erreicht ist, werden weitere Anfragen abgelehnt. Dies wird durch die Rate-Limit-Header signalisiert.
Wie werden Fehler bei der Generierung behandelt?
Fehlerhafte Anfragen werden vollständig erstattet. Wenn die Synthese fehlschlägt, wird der Betrag von Ihrem Guthaben abgezogen und sofort wieder gutgeschrieben. Sie erhalten eine Fehlermeldung im JSON-Response, die den Grund für den Fehler angibt, ohne dass Kosten entstehen.
Kann ich die Stimme ändern, während die API läuft?
Ja, Sie können bei jeder neuen Anfrage eine andere Stimme angeben. Die acht verfügbaren Stimmen (z. B. aria, nova, felix) können dynamisch im voice-Parameter der JSON-Anfrage gewählt werden. Es gibt keine feste Zuordnung pro Sitzung oder Konto.
Wie wird die Geschwindigkeit eingestellt?
Die Geschwindigkeit wird über den Parameter speed im Bereich von 0.25 bis 4.0 gesteuert. Der Standardwert ist 1.0. Dies ermöglicht eine Anpassung der Sprachausgabe an verschiedene Kontexte, wie z. B. langsamere Erklärungen oder schnellere Benachrichtigungen.
Gibt es ein Limit für die Textlänge?
Ja, der Text pro Anfrage darf maximal 4096 Zeichen umfassen. Bei längeren Texten müssen Sie diese in passende Teile aufteilen und die Audiodateien später zusammenfügen. Leerzeichen und Satzzeichen zählen als Zeichen. Dies gilt für beide Modelle tts-1 und tts-1-hd.
Wie wird die Sprache erkannt?
Die Sprache wird automatisch anhand des Schriftbildes erkannt. Bei lateinischem Text wird standardmäßig Englisch angenommen. Für andere Sprachen mit lateinischem Alphabet sollten Sie das Feld language explizit setzen. Unterstützt werden 23 Sprachen, darunter Deutsch, Englisch und Französisch.
Erste Anfrage
curl
curl https://api.playnb66.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.playnb66.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.playnb66.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 | |
|---|---|
aria | weiblich |
nova | weiblich |
luna | weiblich |
sage | weiblich |
felix | männlich |
milo | männlich |
atlas | männlich |
orion | männlich |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
Erste Schritte mit der API
Die API-Integration beginnt mit der Generierung Ihres individuellen API-Schlüssels auf der Seite /get-api-key/. Nach der Registrierung via Google oder E-Mail-Zugangsdaten wird ein aktiver Schlüssel bereitgestellt, der für alle Anfragen verwendet wird. Dieser Schlüssel ist einzigartig pro Konto und Site.
Für die Kommunikation nutzen Sie den Endpunkt https://api.playnb66.com/v1/audio/speech. Die Authentifizierung erfolgt standardmäßig über den HTTP-Header "Authorization: Bearer <Ihr_Schlüssel>". Stellen Sie sicher, dass Ihr Schlüssel korrekt formatiert ist, um Fehler bei der Anfrage zu vermeiden.
API-Key generieren
Erstellen Sie Ihr Konto über /get-api-key/. Nach der Validierung wird Ihnen ein Bearer-Token zugewiesen. Dieses Token ist Ihr Zugriffsmittel für alle API-Endpunkte.
- Unterstützung für Google-Login und E-Mail-Registrierung
- Ein aktiver Schlüssel pro Konto
Endpunkt-URL
Die Haupt-URL für Audio-Anfragen lautet https://api.playnb66.com/v1/audio/speech. Dies ist ein REST-Endpunkt, der JSON-Bodys erwartet und Audio-Dateien zurückgibt.
- Protokoll: HTTPS
- Methode: POST
- Format: JSON
Authentifizierung
Jede Anfrage muss den Header "Authorization: Bearer tts-..." enthalten. Der Schlüssel wird automatisch mit Ihrer Kontoverbindung verknüpft. Bei Verlust kann ein neuer Schlüssel generiert werden, wodurch der alte sofort ungültig wird.
- Header-Name: Authorization
- Wert: Bearer <Ihr_Schlüssel>
- Einmalige Gültigkeit pro Schlüssel
cURL Beispielanfrage
Die API erwartet JSON-Payloads mit definierten Feldern. Ein minimales Beispiel benötigt nur Model und Input. Optional sind Voice, Format und Geschwindigkeit.
Die Struktur ist kompatibel mit bestehenden TTS-Implementierungen. Parameter werden serverseitig validiert. Fehlerhafte Eingaben führen zu sofortiger Rückmeldung.
JSON Body Struktur
Das Request-Body ist ein standardisiertes JSON-Objekt. Es enthält das Textinput und das zu verwendende Modell.
Optionale Felder steuern Stimme und Audioformat. Die Geschwindigkeit liegt zwischen 0.25 und 4.0.
model: tts-1 oder tts-1-hdinput: Textstring, max. 4096 Zeichenvoice: z. B. aria, felix, atlasresponse_format: mp3, wav, opus, flac, pcmspeed: Float, Bereich 0.25–4.0language: ISO-Code (optional)
Parameter Erklärung
Das Feld input enthält den zu synthetisierenden Text. Leerzeichen und Interpunktion zählen als Zeichen.
Die voice bestimmt die Stimme. Pro Anfrage wird genau eine Stimme verwendet. Das Modell tts-1-hd bietet höhere Qualität.
Antwortformat
Bei Erfolg erhalten Sie Audio-Daten im Binärformat. Der Header Content-Type gibt das Format an.
Fehler werden als JSON mit einer Fehlermeldung zurückgegeben. Die HTTP-Status-Codes zeigen den Status an.
Integration mit OpenAI SDK
Die OpenAI SDKs funktionieren bereits mit unserer API, sobald Sie die base_url auf https://api.playnb66.com/v1 anpassen und Ihren API-Key verwenden. Dies ermöglicht eine direkte Integration in bestehende Python- oder Node.js-Umgebungen ohne zusätzliche Bibliotheken.
Das SDK erwartet die gleichen JSON-Strukturen wie der Original-Endpunkt. Durch die Anpassung der Basis-URL leitet das SDK Anfragen korrekt an unseren Dienst weiter, wobei Authentifizierung und Fehlerbehandlung standardmäßig behandelt werden.
Base URL ändern
Ersetzen Sie die Standard-Basis-URL der Bibliothek durch https://api.playnb66.com/v1. Dies stellt sicher, dass alle API-Aufrufe an unsere Infrastruktur gerichtet werden.
Der Pfad /v1/audio/speech bleibt erhalten. Die Authentifizierung erfolgt über den Header Authorization: Bearer <IHR_API_KEY>.
- Base URL: https://api.playnb66.com/v1
- Auth Header: Bearer tts-...
Client Initialisierung
Initialisieren Sie den Client mit Ihrem generierten API-Schlüssel. Das SDK übernimmt die Serialisierung der Anfrage und die Deserialisierung der Audioantwort.
Stellen Sie sicher, dass Ihre Umgebungsvariablen den Schlüssel enthalten, um Hardcoding zu vermeiden und die Sicherheit zu gewährleisten.
- OpenAI(api_key="tts-...")
- Base URL Konfiguration aktiv
Code Beispiel
Das folgende Python-Beispiel zeigt die minimale Implementierung zur Generierung von Sprachausgabe. Der Client sendet Text und empfängt das Audio-Format.
Passen Sie Parameter wie voice und model an Ihre Anforderungen an. Das SDK verarbeitet die Antwort zurück in eine Datei.
import OpenAI client = OpenAI(base_url="https://api.playnb66.com/v1", api_key="tts-...") with client.audio.speech.create( model="tts-1", voice="nova", input="Willkommen in der API-Dokumentation." ) as response: response.stream_to_file("output.mp3")
Verfügbare Parameter
Die API akzeptiert nur die Parameter model, input, voice, response_format, speed und language. Jede Abweichung führt zu einem Fehler. Die Parameter sind strikt definiert, um die Konsistenz in SaaS-Produkten zu gewährleisten.
Model Auswahl
Verwenden Sie tts-1 für Standardqualität oder tts-1-hd für höhere Audioqualität. Beide Modelle nutzen denselben Engine-Backend und haben denselben Preis von 0,01 $ pro 1.000 Zeichen. Die Wahl des Modells ändert nichts an der Latenz oder den verfügbaren Stimmen.
Voice Auswahl
Wählen Sie aus acht vordefinierten Stimmen (aria, nova, luna, sage, felix, milo, atlas, orion). Jede Stimme kann alle 23 unterstützten Sprachen sprechen. Geben Sie bei lateinischem Text, der nicht Englisch ist, unbedingt das ISO-Sprachkürzel an, da sonst Englisch als Standard vermutet wird.
Geschwindigkeit
Der Parameter speed liegt im Bereich von 0,25 bis 4,0. Der Standardwert ist 1,0. Erhöhte Geschwindigkeiten können die Aussprache in komplexen Sätzen beeinträchtigen. Senken Sie die Geschwindigkeit bei technischen Anleitungen, um die Verständlichkeit zu erhöhen.
Audioformate und Ausgabe
Die API unterstützt die Ausgabeformate MP3, WAV, OPUS, FLAC und PCM. Das gewählte Format bestimmt die Dateistruktur der Antwort, nicht die Qualität der Synthese. Alle Formate werden im Response-Body zurückgegeben.
MP3, WAV, OPUS, FLAC, PCM
Wählen Sie mp3 für kompakte Dateigrößen oder wav/flac für verlustfreie Audiodaten. opus bietet eine hohe Effizienz bei niedriger Latenz. pcm liefert rohe PCM-Daten. Die Wahl liegt bei Ihnen, basierend auf Ihrer Infrastruktur.
Stream vs. Datei
Die API gibt die Audiodatei direkt im Antwortbody zurück. Es gibt keinen Streaming-Endpunkt für Echtzeit-Audio.
Invisible Watermark
Jede generierte Audiodatei enthält einen unsichtbaren Wasserzeichen-Marker. Dieser kennzeichnet die Ausgabe eindeutig als synthetische Sprache, ohne die Hörqualität zu beeinträchtigen.

Fehlerbehandlung
Die API gibt bei Fehlern klare HTTP-Statuscodes zurück. Ein 4xx-Fehler bedeutet oft ein Problem im Request, ein 5xx-Fehler ein internes Problem. Fehlgeschlagene Synthesen werden nicht abgerechnet; der Betrag wird vollständig erstattet.
Für eine robuste Integration sollten Sie Fehler abfangen und bei transienten Fehlern (5xx) eine exponentielle Backoff-Strategie implementieren. Dies verhindert unnötige Rate-Limit-Überschreitungen bei temporären Serverlastspitzen.
HTTP Status Codes
Nutzen Sie den Response-Header und Body, um den Fehlertyp zu identifizieren. 400 steht für ungültige Parameter, 401 für falsche oder abgelaufene API-Keys. 429 signalisiert, dass das Ratenlimit erreicht ist.
Bei einem 500-Fehler können Sie den Request sicher wiederholen. Die Abrechnung erfolgt erst nach erfolgreicher Generierung oder explizitem Fehlerstatus.
- 400 Bad Request: Ungültiges JSON oder fehlende Felder.
- 401 Unauthorized: Ungültiger API-Key.
- 429 Too Many Requests: Limit von 60 Requests/Min überschritten.
- 500 Internal Server Error: Vorübergehender Fehler.
Rate Limits
Pro API-Key sind 60 Requests pro Minute erlaubt. Vor der ersten Aufladung liegen die Limits bei 10 Requests pro Minute.
Bei Überschreitung erhalten Sie einen 429-Status. Warten Sie, bis das Limit sich im Fenster von 60 Sekunden wieder auffüllt.
- Standardlimit: 60 Requests/Minute pro Key.
- Initiallimit: 10 Requests/Minute.
- Limit-Header im Response prüfen.
Wiederverwendung
API-Keys können jederzeit neu generiert werden. Der alte Key wird sofort deaktiviert. Dies ist nützlich bei Verdacht auf Kompromittierung.
Cachen Sie den API-Key sicher in Ihrer Backend-Konfiguration. Vermeiden Sie die direkte Ausgabe im Frontend, wenn nicht nötig.
- Key-Neugenerierung sofort wirksam.
- Sichere Speicherung im Backend empfohlen.
Ratenlimits und Throttling
Die API begrenzt die Anzahl der gleichzeitigen Anfragen, um eine stabile Verarbeitungsgarantie zu gewährleisten. Jeder API-Key unterliegt einem festen Limit von 60 Requests pro Minute. Dieses Kontingent gilt pro Schlüssel und nicht pro Konto.
60 Requests pro Minute
Nach Erreichen des Limits von 60 Requests pro Minute werden weitere Anfragen sofort abgelehnt. Eine Verzögerung oder Warteschlange findet nicht statt, bis das Zeitfenster zurückgesetzt wird.
- Limit gilt pro API-Key
- Keine automatische Warteschlange nach Erreichen des Limits
10 Requests initial
Neue Konten starten mit einem reduzierten Limit von 10 Requests pro Minute. Dieses Limit bleibt bestehen, bis die erste Top-up-Zahlung erfolgreich verbucht wurde. Nach der Gutschrift steigt das Limit automatisch auf 60 Requests pro Minute.
Warteschlangenverarbeitung
Die Verarbeitung der Anfragen erfolgt sequentiell. Unter Last kann die Generierung von Audio Dateien länger dauern, da Requests nacheinander abgearbeitet werden. Dies geschieht unabhängig vom Ratenlimit.
- Sequenzielle Verarbeitung unter Last
- Verzögerungen durch Warteschlange, nicht durch Limit-Verweigerung
Beispiel für lange Texte
Die API akzeptiert maximal 4096 Zeichen pro Anfrage. Für längere Texte müssen Sie den Eingabetext vor der Verarbeitung in passende Segmente aufteilen, die dieses Limit nicht überschreiten. Jedes Segment wird als separate HTTP-Anfrage gesendet.
Chunking Strategie
Teilen Sie den Text an logischen Grenzen, etwa nach Sätzen oder Absätzen, auf. Stellen Sie sicher, dass jedes Chunk maximal 4096 Zeichen umfasst, einschließlich Leerzeichen und Satzzeichen. Dies gewährleistet eine konsistente Generierung und vermeidet Fehler bei der Verarbeitung.
Audio Zusammenführung
Jedes Chunk generiert eine eigene Audiodatei. Diese Dateien müssen nach dem Download sequenziell zu einer einzigen Audiodatei zusammengeführt werden. Die Reihenfolge der Dateien muss exakt der Reihenfolge der Chunks im Originaltext entsprechen, um die narrativen Struktur zu wahren.
Fehlervermeidung
Behandeln Sie jeden Chunk als isolierte Anfrage. Bei einem Fehler in einem Segment wird nur dieser Teil nicht berechnet, während andere erfolgreich bleiben. Dies ermöglicht eine gezielte Wiederholung ohne Neustart des gesamten Prozesses.
Hören Sie sich die 8 Stimmen an
Jede der folgenden Samples wurde von dieser API aus demselben Satz generiert. Wir gestalten intuitive Benutzeroberflächen für nahtlose SaaS-Benachrichtigungen, die Produktteams bei der effizienten Steuerung ihrer täglichen Arbeitsabläufe unterstützen.
23 Sprachen
Jede Stimme kann jede dieser Sprachen sprechen.
