API Dokumentation für Entwickler: Endpunkte, Parameter und Integration

Von Spruchkraft Redaktionskollegium · Aktualisiert 2026-11-18

Diese Dokumentation beschreibt die Integration der Spruchkraft Text-to-Speech API für Produktteams, die konsistente Sprachausgaben in SaaS-Plattformen benötigen. Sie erläutert die REST-Endpunkte, Parameter und Authentifizierung, um Audio-Dateien direkt in Benutzeroberflächen zu generieren. Alle Beispiele basieren auf cURL und dem OpenAI SDK, das durch Anpassung der Base URL funktioniert.

Entwickler erhalten konkrete Anleitungen zu Modellwahl, Stimmenauswahl und Geschwindigkeitssteuerung. Die Seite erklärt auch die Handhabung von Ratenlimits, Fehlercodes und die Verarbeitung langer Texte durch Chunking. Die technischen Details sind auf die Anforderungen industrieller Interfaces abgestimmt, ohne unnötige Komplexität.

API Dokumentation für Entwickler: Endpunkte, Parameter und Integration

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.mp3

Python (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
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 mit der API

Schallwellenillustration für: 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

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

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

Schallwellenillustration für: 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-hd
  • input: Textstring, max. 4096 Zeichen
  • voice: z. B. aria, felix, atlas
  • response_format: mp3, wav, opus, flac, pcm
  • speed: Float, Bereich 0.25–4.0
  • language: 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

Schallwellenillustration für: 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

Schallwellenillustration für: 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

Schallwellenillustration für: 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.

Audioformate und Ausgabe

Fehlerbehandlung

Schallwellenillustration für: 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

Schallwellenillustration für: 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

Schallwellenillustration für: 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.

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. ISO 639 language codes
  3. curl documentation
  4. LibriTTS-R corpus (OpenSLR 141)
  5. FFmpeg documentation
  6. Node.js documentation
  7. openai-python on GitHub
  8. OpenAI API reference: create speech
  9. Python documentation
  10. openai-node on GitHub
  11. MDN: Web Speech API
  12. Tether (USDT)

Mehr auf dieser Website