TTS API: Text-to-Speech Integration, Endpunkte, Stimmen und Parameter im Detail

Von Sprachgeist Redaktionsteam · Aktualisiert 2026-11-18

Diese Dokumentation erklärt die Integration der Sprachgeist-API für Indie-Entwickler, die NPC-Dialoge oder Audiobooks programmatisch generieren möchten. Sie erhalten eine präzise Übersicht über Authentifizierung, verfügbare Endpunkte und alle notwendigen Parameter, um Audio-Clips direkt in Ihre Spiel-Engine zu senden.

Wir beschreiben schrittweise den Workflow von der Schlüssel-Erzeugung bis zur Fehlerbehandlung. Die Beispiele nutzen Standard-cURL-Befehle und die OpenAI-SDKs, da die Schnittstelle kompatibel ist. So können Sie sich auf das Game Design konzentrieren, während wir die Text-zu-Sprache-Umwandlung übernehmen.

TTS API: Text-to-Speech Integration, Endpunkte, Stimmen und Parameter im Detail

Häufig gestellte Fragen

Wie erhalte ich einen API-Key?

Registriere dich auf /get-api-key/ mit Google oder E-Mail. Nach der Anmeldung siehst du deinen Schlüssel, das Guthaben, die Testphase, die verbleibenden Zeichen, die Nutzung und ein fertiges curl-Beispiel. Pro Konto ist nur ein aktiver Schlüssel verfügbar. Du kannst jederzeit einen neuen Schlüssel ausstellen, wodurch der alte sofort ungültig wird.

Welche Bibliotheken werden unterstützt?

Wir nutzen keine eigene SDK-Bibliothek. Da die API dem OpenAI-Format entspricht, funktionieren die offiziellen OpenAI-SDKs, sobald du die base_url auf https://api.playi44.com/v1 änderst. Alternativ lässt sich die Schnittstelle mit jeder HTTP-Bibliothek integrieren, die JSON-Payloads unterstützt, was eine direkte und unkomplizierte Anbindung in deine Anwendung ermöglicht.

Wie funktioniert die Authentifizierung?

Übergebe deinen Schlüssel im Header als Authorization: Bearer tts-.... Pro Konto gibt es genau einen aktiven Schlüssel. Ein neuer Schlüssel macht den alten sofort ungültig. Dies gewährleistet einfache Verwaltung und Sicherheit für deine Indie-Game-Projekte ohne komplexe Token-Flows.

Welche Modelle sind verfügbar?

Verfügbar sind tts-1 und tts-1-hd. Beide nutzen dieselbe Engine und haben denselben Preis. Der Unterschied liegt in der Audioqualität. Wähle tts-1-hd für hochwertigeren Sound oder tts-1 für Standardleistung. Beide akzeptieren dieselben Parameter für Stimme, Format und Geschwindigkeit.

Wie ändere ich die Geschwindigkeit?

Nutze den Parameter speed im JSON-Body. Der Wertebereich liegt zwischen 0.25 und 4.0. Dies erlaubt dir, NPC-Dialoge präzise an den Kontext anzupassen. Ein höherer Wert beschleunigt die Aussprache, ein niedrigerer verlangsamt sie. Dies ist ideal für dramatische oder schnelle Dialogsequenzen.

Kann ich die Sprache festlegen?

Ja, setze den Parameter language mit einem ISO-Code. Ohne Angabe wird die Sprache aus dem Skript erraten (Lateinstandard ist Englisch). Für nicht-englische Texte in lateinischer Schrift solltest du die Sprache explizit setzen. Unterstützt werden 23 Sprachen, darunter Deutsch, Englisch und Japanisch.

Was bedeutet response_format?

Der Parameter response_format definiert das Ausgabeformat: mp3, wav, opus, flac oder pcm. Opus bietet hohe Kompression, WAV und FLAC sind verlustfrei, PCM liefert Rohdaten. Da die API stets die vollständige Audiodatei zurückgibt und kein Streaming unterstützt, wähle das Format, das am besten zu deiner Game-Engine passt.

Wie lange ist die Antwort verzögert?

Kurze Sätze benötigen einige Sekunden. Bei längeren Texten beträgt die Generierungsgeschwindigkeit etwa Echtzeit, was rund 25 Zeichen pro Sekunde entspricht. Da Anfragen nacheinander verarbeitet werden, können sie unter Last in einer Warteschlange stehen. Plane daher Pufferzeiten für die NPC-Dialoggenerierung ein, um Verzögerungen zu vermeiden.

Was passiert bei Rate Limits?

Das Limit liegt bei 60 Anfragen pro Minute pro Schlüssel. Vor der ersten Aufladung sind es nur 10 pro Minute. Überschreitungen führen zu Fehlern, aber die Abrechnung bleibt fair. Fehlerhafte Synthesen werden kostenlos gestellt. Plane deine Batch-Generierung entsprechend dieser Limits ein.

Gibt es eine Sandbox-Umgebung?

Eine separate Sandbox-Umgebung gibt es nicht. Du kannst Integrationstests direkt in der Produktionsumgebung durchführen, da das Startguthaben von 0,50 $ (ca. 50.000 Zeichen) nach der Google-Anmeldung sieben Tage gültig ist. So prüfst du die Anbindung risikofrei, bevor du Guthaben per USDT (TRC-20) auflädst.

Wie wird der API-Key geschützt?

Der Schlüssel wird im Authorization-Header übergeben. Pro Konto ist nur ein Schlüssel aktiv. Du kannst jederzeit einen neuen Schlüssel ausstellen, wodurch der alte sofort ungültig wird. Dies ermöglicht schnelles Rotieren bei Verdacht auf Kompromittierung ohne komplexe Berechtigungsstrukturen oder Warteschleifen.

Kann ich den Base URL ändern?

Ja, setze die base_url in deinen SDKs auf https://api.playi44.com/v1. Dies ermöglicht die Nutzung der offiziellen OpenAI-SDKs mit minimalem Aufwand. Die Anfragestruktur entspricht dem OpenAI-Schema. Du musst nur die URL anpassen und deinen eigenen API-Schlüssel verwenden.

Werden Logs gespeichert?

Wir speichern nur Metadaten wie Zeit, Zeichenanzahl und Status zur Abrechnung. Der Eingabetext wird ausschließlich zur Audioerstellung verwendet und nicht zum Training weiterverwendet. Generierte Audio-Dateien werden nach der Auslieferung nicht auf unseren Servern gespeichert. So bleibt deine Eingabe privat und du behältst die volle Kontrolle über deine Daten.

Wie lange sind die Audio-Dateien verfügbar?

Die Audio-Dateien werden direkt in der API-Antwort zurückgegeben und nicht auf unseren Servern gespeichert. Sie sind daher nur so lange verfügbar, wie du sie lokal speicherst oder in deinem Spielcached ablegst. Es gibt keine persistente Speicherung der generierten Audiodaten auf unseren Servern.

Erste Anfrage

curl

curl https://api.playi44.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.playi44.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.playi44.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

API-Key erhalten

Schallwellenillustration für: API-Key erhalten

Die API-Nutzung beginnt mit der Erstellung eines Kontos auf der Seite /get-api-key/. Hier wählst du zwischen Anmeldung über Google oder E-Mail. Bei Google-Authentifizierung erhältst du sofort einen Testguthaben von 0,50 $ (ca. 50.000 Zeichen), das sieben Tage gültig ist. E-Mail-Konten starten ohne Guthaben.

Registrierung

Erstelle dein Konto über /get-api-key/. Die Authentifizierung erfolgt entweder via Google oder klassisch mit E-Mail und Passwort. Das Konto ist standortabhängig an playi44.com gebunden.

Key kopieren

Nach der Anmeldung siehst du deinen einzigartigen API-Schlüssel (tts-...). Kopiere diesen sofort, da er nur einmalig angezeigt wird. Für Authentifizierung füge den Header Authorization: Bearer <dein_key> in deine Requests ein.

Key erneuern

Du kannst jederzeit einen neuen Schlüssel generieren. Sobald der neue Key aktiv ist, wird der vorherige sofort ungültig. Dies ist nützlich, wenn du den Key in öffentlichen Repositories teilst oder ihn kompromittiert vermutest.

Erste Anfrage

Schallwellenillustration für: Erste Anfrage

Nach dem Erhalt deines API-Keys ist der erste Schritt die direkte Anbindung an die Engine. Wir demonstrieren hier die Integration über ein Standard-cURL-Kommando, das Texteingabe und Audioausgabe in einem Schritt abbildet. Dies dient als Basis für alle weiteren Skripte in deinem Spiel-Backend.

cURL Befehl

Führe folgenden Befehl im Terminal aus. Er sendet eine POST-Anfrage an den Speech-Endpunkt. Achte darauf, den Platzhalter DEIN_API_KEY durch deinen individuellen Key zu ersetzen. Die Antwort landet als binäre Datei im aktuellen Verzeichnis.

JSON Body

Der Request-Body ist ein JSON-Objekt. Das Feld input enthält den NPC-Dialogtext (max. 4096 Zeichen). Der voice-Parameter bestimmt die NPC-Stimme, z. B. atlas für neutrale Nachrichten oder sage für ruhige Anweisungen. model kann tts-1 oder tts-1-hd sein.

Antwort formatieren

Die API antwortet mit dem rohen Audio-Binärstream. Speichere diesen direkt in eine Datei mit der passenden Endung (z. B. .mp3 oder .wav). Jede generierte Datei enthält ein unsichtbares Wasserzeichen, das den synthetischen Ursprung kennzeichnet.

Erste Anfrage

OpenAI SDK

Schallwellenillustration für: OpenAI SDK

Die API ist vollständig kompatibel mit den offiziellen OpenAI-SDKs. Du musst lediglich die base_url auf https://api.playi44.com/v1 setzen und deinen API-Schlüssel verwenden. So funktioniert die Integration direkt mit bekanntem Code.

Base URL ändern

Setze die Basis-URL des SDKs auf https://api.playi44.com/v1. Dies ermöglicht die Nutzung bestehender Bibliotheken ohne neue Client-Implementierung. Der Authentifizierungsheader bleibt Authorization: Bearer <dein_schlüssel>.

Python Beispiel

Importiere openai und setze die Base URL. Der Code generiert Audio synchron. Da die Antwort Sekunden dauern kann, eignet sich dies gut für dynamische Dialoge mit kurzer Wartezeit, nicht für Streaming.

  • from openai import OpenAI
  • client = OpenAI(base_url="https://api.playi44.com/v1", api_key="tts-...")
  • response = client.audio.speech.create(model="tts-1", voice="nova", input="Hallo Welt", response_format="mp3")

Node.js Beispiel

Endpunkte

Schallwellenillustration für: Endpunkte

Die API-Kommunikation erfolgt über drei klare Endpunkte. Der Hauptendpunkt verarbeitet Texteingaben und generiert Audio, während die anderen Informationen zu verfügbaren Stimmen und Modellen bereitstellen.

Alle Endpunkte erfordern die Authentifizierung über den Bearer-Token im Header. Die Antwortdaten sind im JSON-Format strukturiert und enthalten die notwendigen Metadaten für die Integration.

POST /v1/audio/speech

Dieser Endpunkt empfängt JSON-Payloads mit Text bis 4096 Zeichen und generiert daraus Audiodateien. Unterstützte Formate umfassen MP3, WAV, OPUS, FLAC und PCM. Die Parameter model, voice und speed steuern die Ausgabe.

Die Antwort enthält direkt die Audio-Daten oder Fehlercodes bei ungültigen Eingaben. Die Authentifizierung erfolgt über den Authorization: Bearer Header.

  • JSON-Body mit Feldern input, voice, model, response_format
  • Maximale Textlänge: 4096 Zeichen pro Anfrage
  • Unterstützte Formate: mp3, wav, opus, flac, pcm

GET /v1/voices

Ruft eine Liste aller verfügbaren Stimmen und deren Metadaten ab. Die Antwort enthält Informationen zu Sprache, Geschlecht und technischen Eigenschaften der 8 Presets.

Dieser Endpunkt ist nützlich, um dynamisch die richtigen Stimmen für verschiedene NPC-Typen in Spielen auszuwählen. Die Daten sind direkt für die API-Nutzung aufbereitet.

  • Listet alle 8 verfügbaren Stimmen auf
  • Enthält Metadaten zu Sprache und Stimme
  • Ergebnisformat: JSON-Array mit Stimme-Details

GET /v1/models

Zeigt die verfügbaren Modelle an (tts-1 und tts-1-hd). Beide nutzen dieselbe Engine und haben denselben Preis.

Die Modellinformationen sind statisch und ändern sich nicht häufig. Sie dienen der Bestätigung der technischen Konfiguration.

  • Verfügbare Modelle: tts-1, tts-1-hd
  • Gleiche Engine und Preis für beide
  • Statische Konfigurationsdaten

Parameter

Schallwellenillustration für: Parameter

Die API-Parameter steuern präzise die Generierung der NPC-Dialoge. Die Wahl von model, voice und speed bestimmt, wie der Text in Audio umgewandelt wird, ohne dass zusätzliche Konfigurationsdateien nötig sind.

Model auswählen

Wähle zwischen tts-1 und tts-1-hd. Beide nutzen dieselbe Engine und kosten gleich viel (0,01 $ pro 1.000 Zeichen). Die Entscheidung liegt allein bei deiner Präferenz für das Audioformat.

Voice wählen

Verfügbare Stimmen umfassen aria, nova, luna, sage, felix, milo, atlas und orion. Jede Stimme kann jede der 23 unterstützten Sprachen sprechen, sodass du für NPCs keine separaten Modelle brauchst.

Speed anpassen

Der speed-Parameter akzeptiert Werte zwischen 0,25 und 4,0. Dies erlaubt es, Dialoge präzise an die Sprechweise deines Spiels anzupassen, ohne die Qualität der Synthese zu beeinträchtigen.

Parameter

Audioformate

Schallwellenillustration für: Audioformate

Das API unterstützt mehrere Audioformate, die du direkt über das Feld response_format in deiner Anfrage auswählst. Die Wahl des Formats hängt vom Verwendungszweck ab: MP3 und WAV sind weit verbreitet, während OPUS, FLAC und PCM für spezifische Streaming- oder Archivierungsbedürfnisse geeignet sind.

MP3

MP3 ist das Standardformat für die meisten Indie-Game-Engines und bietet eine gute Balance zwischen Dateigröße und Qualität. Es eignet sich hervorragend für NPC-Dialoge, die im Hintergrund abgespielt werden, da es wenig Speicherplatz beansprucht und von den meisten Plattformen nativ unterstützt wird.

WAV

WAV bietet verlustfreie Audioqualität und ist ideal, wenn du die Audiodateien in deiner Produktionspipeline weiterverarbeitest oder wenn Latenz und Komprimierungsartefakte kritisch sind. Es ist das bevorzugte Format für hochwertige Dialogbäume, bei denen die phonetische Klarheit im Vordergrund steht.

OPUS/FLAC/PCM

Für spezifische Anforderungen stehen OPUS, FLAC und PCM zur Verfügung. OPUS ist effizient für Streaming-Szenarien, FLAC bietet verlustlose Kompression für Archivzwecke und PCM liefert rohe Audiodaten ohne Header. Diese Formate bieten Flexibilität für fortgeschrittene Integrationsfälle, die über Standard-MP3 hinausgehen.

Fehlerbehandlung

Schallwellenillustration für: Fehlerbehandlung

Fehler sind Teil des Betriebs. Ein fehlgeschlagener Request wird kostenlos berechnet, da die Gebühr im Fehlerfall vollständig erstattet wird. Dies schützt dein Budget bei temporären Ausfällen der Synthese-Engine.

Die API gibt klare HTTP-Statuscodes zurück, damit du Fehler programmatisch abfangen und deine Game-Logik entsprechend anpassen kannst.

401 Unauthorized

Dieser Fehler tritt auf, wenn dein API-Key ungültig oder abgelaufen ist. Prüfe, ob du den Key korrekt im Header als Authorization: Bearer tts-... überträgst.

429 Rate Limit

Du hast das Kontingent überschritten. Das Limit liegt bei 60 Requests pro Minute für aktive Keys. Bei neuen Accounts ohne Top-up sind es zunächst 10 Requests pro Minute.

Warte kurz ab oder erhöhe dein Limit durch eine Top-up-Zahlung. Wartezeiten durch Warteschlangen sind normal.

500 Server Error

Ein interner Serverfehler bedeutet, dass die Synthese kurzzeitig nicht erfolgreich war. Der Request wird nicht berechnet, da die Gebühr im Fehlerfall vollständig erstattet wird.

Versuche den Request mit einer kurzen Verzögerung erneut.

Fehlerbehandlung

Rate Limits

Schallwellenillustration für: Rate Limits

Die API nutzt ein Tokensystem zur Steuerung der Anfragen. Pro Minute sind maximal 60 Requests erlaubt, was für die meisten Indie-Game-Szenarien ausreicht. Bei Überschreitung folgt ein 429-Fehler.

60 Requests/Minute

Jeder API-Key kann bis zu 60 Anfragen pro Minute verarbeiten. Dies ermöglicht flüssige Dialoggenerierungen, solange keine extrem langen Texte parallel verarbeitet werden. Der Verbrauch wird im Dashboard genau überwacht.

10 Requests/Minute (Start)

Neue Konten starten mit einem Limit von 10 Requests pro Minute. Dies schützt vor Missbrauch und ermöglicht kontrollierte Tests. Nach der ersten Top-Up-Zahlung wird das Limit automatisch auf 60 Requests/Minute angehoben.

Warteschlange

Anfragen werden sequenziell abgearbeitet. Bei hoher Last kann es zu kurzen Wartezeiten in der Warteschlange kommen. Die Generierung dauert bei längeren Texten etwa so lang wie die Audiodauer selbst.

Hören Sie sich die 8 Stimmen an

Jede der folgenden Samples wurde von dieser API aus demselben Satz generiert. Die NPC-Dialoge lebten auf, als wir sie mit feinen Nuancen und subtilem Emotionsspiel versehen haben.

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. W3C WAI: making audio and video accessible
  3. LibriTTS-R corpus (OpenSLR 141)
  4. LibriVox public-domain audiobooks
  5. Tether (USDT)
  6. FFmpeg documentation
  7. Creative Commons Attribution 4.0
  8. curl documentation
  9. openai-node on GitHub
  10. TRON developer hub: TRC-20
  11. OpenAI API reference: create speech
  12. MDN: Web Speech API

Mehr auf dieser Website