Häufig gestellte Fragen
Wie erstelle ich einen API-Key?
Registriere dich auf /get-api-key/ via Google oder E-Mail. Du erhältst sofort einen aktiven Bearer-Key. Pro Konto ist nur ein Schlüssel aktiv; bei Neuausstellung wird der alte sofort gesperrt. Die Seite zeigt auch deinen Kontostand und ein curl-Beispiel zur direkten Nutzung der API.
Welche SDKs werden unterstützt?
Wir bieten kein eigenes SDK. Da die API dem OpenAI-Format entspricht, funktionieren die offiziellen OpenAI-SDKs, indem du die base_url auf https://api.1971games.info/v1 änderst und deinen API-Schlüssel verwendest. Alternativ kannst du einfache HTTP-Anfragen direkt nutzen.
Wie ändere ich die Stimme?
Ändere das Feld voice im JSON-Body deiner POST-Anfrage an /v1/audio/speech. Wähle aus acht Presets wie Aria, Nova oder Felix. Die Stimme passt sich automatisch der Sprache an. Falls nötig, setze das optionale Feld language explizit, um die Erkennung zu steuern.
Welche Formate werden unterstützt?
Du kannst response_format auf mp3, wav, opus, flac oder pcm setzen. Diese Optionen stehen dir direkt im Request-Body zur Verfügung. Das gewählte Format wird im Antwort-Stream als Audio-Datei zurückgegeben. Andere Formate wie m4a oder aac werden nicht unterstützt.
Was sind Rate Limits?
Das Limit beträgt 60 Anfragen pro Minute pro Schlüssel. Vor der ersten Aufladung gelten 10 Anfragen pro Minute. Anfragen werden nacheinander verarbeitet, was bei hoher Last zu Warteschlangen führen kann. Längere Texte müssen vom Client in Teile unter 4096 Zeichen aufgeteilt werden.
Wie gehe ich mit Fehlern um?
Bei fehlgeschlagenen Anfragen wird der Betrag vollständig erstattet. Du erhältst keine Abrechnung für fehlgeschlagene Anfragen. Prüfe deine Parameter wie model oder voice und stelle sicher, dass dein Guthaben ausreicht. Die API gibt bei Problemen einen entsprechenden HTTP-Statuscode zurück.
Kann ich die Geschwindigkeit ändern?
Ja, setze das Feld speed im Request auf einen Wert zwischen 0.25 und 4.0. Dies erlaubt dir, die Sprechgeschwindigkeit der synthetischen Stimme präzise anzupassen. Der Standardwert liegt bei 1.0. Ändere den Wert je nach Bedarf für Dialoge oder Erklärungen.
Wie funktioniert die Authentifizierung?
Nutze den Header Authorization: Bearer tts-... mit deinem persönlichen API-Schlüssel. Dieser Schlüssel wird nach der Registrierung im Dashboard angezeigt. Er ist pro Konto gültig und ermöglicht den Zugriff auf die Endpunkte. Achte darauf, den Schlüssel nicht öffentlich zugänglich zu machen.
Erste Anfrage
curl
curl https://api.1971games.info/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.1971games.info/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.1971games.info/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 |
API-Key erstellen
Um die GameTTS API zu nutzen, registrierst du dich über die Seite /get-api-key/ mit Google oder einer E-Mail-Adresse. Nach der Anmeldung erhältst du einen API-Key, der direkt im Dashboard sichtbar ist. Dieser Schlüssel autorisiert deine Anfragen an die Endpunkte der API.
Registrierung
Die Registrierung ist schnell erledigt: Wähle Google für den direkten Zugang oder erstelle ein Konto mit E-Mail und Passwort. Beachte, dass das kostenlose Testguthaben von 0,50 $ nur bei Google-Logins automatisch gewährt wird. E-Mail-Registrierungen starten ohne Guthaben.
Key generieren
Dein API-Key beginnt mit "tts-" und wird im Dashboard angezeigt. Jeder Account verfügt über genau einen aktiven Schlüssel. Du kannst jederzeit einen neuen Key generieren; der alte Schlüssel wird dann sofort ungültig.
Key verwalten
Verwende den Key im HTTP-Header als Authorization: Bearer tts-.... Das Dashboard zeigt dir auch dein aktuelles Guthaben, die verbleibenden Zeichen und eine curl-Vorlage für den schnellen Einstieg.
Erste Anfrage
Nach der Erstellung deines API-Keys in der Konsole bist du bereit für die erste Synthese. Sende einfach einen POST-Befehl an den Endpunkt mit deinem Text und der gewünschten Stimme. Die Antwort enthält direkt die Audiodaten.
curl Beispiel
Nutze curl für schnelle Tests direkt im Terminal. Ersetze DEIN_API_KEY durch deinen Key aus der Konsole.
- curl -X POST https://api.1971games.info/v1/audio/speech \\ -H "Authorization: Bearer DEIN_API_KEY" \\ -H "Content-Type: application/json" \\ -d '{"model": "tts-1", "input": "Hallo Welt", "voice": "aria", "response_format": "mp3"}'
OpenAI SDK
Da die API im OpenAI-Format vorliegt, funktioniert das offizielle OpenAI SDK nahtlos. Ändere einfach die base_url auf unsere Domain und verwende deinen eigenen Key.
- client = OpenAI(base_url="https://api.1971games.info/v1", api_key="DEIN_API_KEY")
Python Beispiel
Dieses Snippet zeigt, wie du Audio-Daten empfängst und speicherst. Ideal für Python-Skripte in deinem Entwicklungsworkflow.
- response = client.audio.speech.create(model="tts-1", voice="nova", input="Test Text", response_format="mp3") response.stream_to_file("output.mp3") # Hinweis: Die OpenAI Python SDK Methode stream_to_file speichert die Datei lokal. Für Unity oder andere Engines werden oft Bytes benötigt.
Parameter
Die API-Parameter steuern direkt, wie Text in Audio verwandelt wird. Du wählst das Modell, die Stimme und die Sprache im JSON-Body deiner POST-Anfrage an /v1/audio/speech.
Jeder Parameter hat einen festen Einfluss auf das Ergebnis. Wir listen hier die verfügbaren Optionen auf, damit du sofort mit der Integration beginnen kannst.
Modell: tts-1
Nutze tts-1 oder tts-1-hd. Beide Modelle nutzen denselben Engine-Standard und kosten gleich viel. Der Unterschied liegt in der Audioqualität und dem Ressourcenbedarf, nicht im Preis.
Stimme: 8 Optionen
Wähle aus 8 vordefinierten Stimmen für deine Dialoge oder Text-to-Speech-Ausgaben. Die Auswahl reicht von warmen Erzählerstimmen bis zu neutralen Nachrichtenstimmen.
Jede Stimme ist klar definiert, z.B. Aria für klare Narration oder Felix für energetische Promo-Texte. Die Stimme bleibt unabhängig von der Sprache konstant, kann aber durch das language-Feld beeinflusst werden.
- Aria (warm, klar)
- Nova (hell, positiv)
- Luna (sanft, erzählerisch)
- Sage (ruhig, anweisend)
- Felix (energetisch)
- Milo (freundlich)
Sprache: ISO Code
Gib die Sprache als optionalen ISO-Code an (z.B. de, en, fr). Wird keine Sprache gesetzt, wird die Sprache basierend auf dem Skript erraten.
Bei lateinischem Text ohne Sprachangabe wird standardmäßig Englisch angenommen. Setze language explizit für andere Sprachen wie Deutsch, Spanisch oder Japanisch.
- de (Deutsch)
- en (Englisch)
- fr (Französisch)
- es (Spanisch)
- ja (Japanisch)
- ko (Koreanisch)
Ausgabeformate
Das API unterstützt vier Audioformate für verschiedene Einsatzszenarien in der Spieleentwicklung. Die Wahl des Formats hängt von der Balance zwischen Dateigröße, Latenz und Qualität ab. Jedes Format wird direkt im Antwort-Body der API-Anfrage zurückgegeben.
Wähle MP3 für die Standardausgabe, WAV für unverarbeitete Qualität, OPUS für effiziente Kompression oder FLAC für verlustfreie Archivierung. Das Format wird im Parameter response_format definiert.
MP3
MP3 ist das Standardformat für die meisten Anwendungen. Es bietet eine gute Balance zwischen Dateigröße und Klangqualität. Die Kompression ist verlustbehaftet, aber für Dialoge und Hintergrundgeräusche in Spielen meist ausreichend. Die Dateigrößen sind klein, was Ladezeiten im Spiel reduziert.
WAV
WAV liefert unverarbeitete PCM-Daten ohne Kompression. Dies ist ideal, wenn du die Audio-Dateien direkt in deine Game-Engine importierst und weitere Effekte anwenden möchtest. Die Dateigrößen sind deutlich größer als bei MP3, aber die Latenz bei der Verarbeitung ist minimal.
OPUS
OPUS bietet eine hohe Effizienz bei sehr kleinen Dateigrößen. Es eignet sich hervorragend für mobile Spiele oder Anwendungen mit begrenzter Bandbreite. Die Qualität bleibt auch bei niedriger Bitrate klar, was OPUS zur besten Wahl für dynamisches Streaming im Spielkontext macht.
Fehlerbehandlung
Die API gibt bei Fehlern klare HTTP-Statuscodes zurück. Ein 400 signalisiert ungültige Parameter, 401 einen fehlenden oder falschen API-Key, und 429 einen überschrittenen Rate Limit. Diese Codes helfen dir, Probleme direkt in deiner Integrationslogik zu identifizieren und korrekt zu handhaben.
HTTP Status Codes
Neben den genannten Fehlern gibt es 500 für Serverprobleme und 503 bei temporärer Überlastung. Nutze diese Codes, um zwischen Konfigurationsfehlern und infrastrukturellen Problemen zu unterscheiden. Eine robuste Fehlerbehandlung prüft immer zuerst den Statuscode, bevor sie die Fehlermeldung analysiert.
- 400: Ungültige Anfrage (z. B. Text zu lang)
- 401: Authentifizierung fehlgeschlagen
- 429: Rate Limit überschritten
- 500: Interner Serverfehler
- 503: Dienst nicht verfügbar
Fehlermeldungen
Jede Fehlerantwort enthält ein JSON-Objekt mit einem message-Feld, das das Problem präzise beschreibt. Lies diese Meldung, um zu verstehen, warum die Synthese fehlgeschlagen ist. Dies ist besonders hilfreich bei der Debugging-Phase, wenn du Parameter wie voice oder model anpasst.
Wiederholungsversuch
Implementiere exponentielles Backoff bei 503 oder 429 Fehlern. Warte kurz und wiederhole die Anfrage, bis sie erfolgreich ist oder das Limit erreicht ist. Vermeide sofortiges Retry bei 400 Fehlern, da diese durch manuelles Eingreifen korrigiert werden müssen. Dies spart API-Kosten und verbessert die Zuverlässigkeit.

Rate Limits
Um stabile Audio-Generierungen für deine Indie-Produktionen zu gewährleisten, setzen wir klare Limits für die API-Nutzung fest. Dies verhindert Engpässe bei hoher Auslastung und sorgt dafür, dass deine Text-zu-Speech-Anfragen zuverlässig verarbeitet werden.
60 Anfragen/Minute
Nach einem Top-up oder einer aktiven Guthabenverbuchung sind 60 API-Anfragen pro Minute pro Schlüssel erlaubt. Dies reicht für die meisten Entwicklungs- und Produktionsworkflows völlig aus.
10 Anfragen/Minute vor Top-up
Neue Konten oder Konten ohne aktuelles Guthaben starten mit einem niedrigeren Limit von 10 Anfragen pro Minute. Dies ermöglicht dir, die API zunächst mit dem kostenlosen Testguthaben von 0,50 $ ausgiebig zu testen.
Warteschlange
Anfragen werden sequentiell verarbeitet. Bei hoher Auslastung kann es vorkommen, dass Anfragen in einer Warteschlange landen und leicht verzögert bearbeitet werden. Dies ist normal und beeinträchtigt die Qualität der Synthese nicht.
Textlängen
Die API akzeptiert pro Anfrage maximal 4096 Zeichen. Dies umfasst Buchstaben, Zahlen, Leerzeichen und Satzzeichen. Längere Texte, wie umfangreiche Dialogbäume oder rechtliche Texte, müssen in kleinere Blöcke unterteilt werden.
4096 Zeichen Limit
Jeder einzelne API-Aufruf ist auf 4096 Zeichen begrenzt. Wenn dein Text länger ist, musst du ihn manuell oder programmatisch in mehrere Abschnitte aufteilen. Jedes Zeichen zählt, auch Leerzeichen.
Splitting bei Bedarf
Teile deine Eingabe an natürlichen Grenzen, z. B. nach Sätzen oder Absätzen. Dies verhindert, dass wichtige Dialoge oder Informationen abgeschnitten werden. Achte darauf, dass kein Text verloren geht.
Audio Zusammenführung
Generiere für jeden Teil die Audio-Datei separat. Füge die Ergebnisse anschließend in deiner Anwendung zusammen. So entsteht ein flüssiges, vollständiges Audio-File, das direkt in dein Spiel oder deine Software integriert werden kann.
Beispiel-Code
Die API ist mit den offiziellen OpenAI-SDKs kompatibel, indem du die base_url anpasst. Dies ermöglicht eine nahtlose Integration in bestehende Indie-Workflows, ohne neue Libraries lernen zu müssen.
Unten findest du konkrete Beispiele für JavaScript, C# und Unity, um Audio-Dateien direkt in deine Game-Engine oder Web-Oberfläche zu laden.
JavaScript
Nutze fetch oder die OpenAI JS Library. Setze base_url auf https://api.1971games.info/v1 und übergebe deinen API-Key im Header.
- Unterstützt alle Antwortformate wie MP3 und WAV.
C#
Installiere das NuGet-Paket OpenAI. Konfiguriere den Client mit der eigenen Base-URL. Der Code bleibt identisch zum Standard-Beispiel.
- Lädt Audio-Daten in den Arbeitsspeicher.
Unity C#
Verwende UnityWebRequest oder die OpenAI Unity SDK. Lade die Audio-Daten als Bytes herunter und speichere sie lokal oder spiele sie direkt ab.
- Ideal für dynamische Dialoge im Spiel.
Hören Sie sich die 8 Stimmen an
Jede der folgenden Samples wurde von dieser API aus demselben Satz generiert. Dies sorgt für Transparenz, ohne die Hörerfahrung zu stören.
23 Sprachen
Jede Stimme kann jede dieser Sprachen sprechen.
