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 sehen Sie Ihren API-Key, das Guthaben und die Zeichenanzahl. Der Key wird im Header als Bearer-Token verwendet. Ein Konto pro Seite ist möglich. Bei Bedarf kann jederzeit ein neuer Key ausgestellt werden, wobei der alte sofort ungültig wird.
Wie ändere ich die Base URL?
Ändern Sie die Base URL in Ihrer Konfiguration auf https://api.vz58.info/v1. Dies ermöglicht die Nutzung der offiziellen OpenAI SDKs. Stellen Sie sicher, dass der API-Key im Authorization-Header korrekt gesetzt ist. Die Request-Struktur entspricht der OpenAI-Speech-Endpunkt-Spezifikation, sodass bestehende Implementierungen leicht angepasst werden können.
Welche Fehlercodes gibt es?
Die Dokumentation listet spezifische Fehlercodes für verschiedene Szenarien auf, wie ungültige Parameter oder Kontingentüberschreitungen. Bei Synthesefehlern wird der Betrag vollständig erstattet. Detaillierte Informationen zu allen möglichen Fehlerantworten und deren Bedeutung finden Sie im Abschnitt zu Fehlerbehandlungen der API-Dokumentation unter /docs/.
Wie hoch ist das Zeichenlimit?
Das Zeichenlimit beträgt 4096 Zeichen pro Anfrage. Längere Texte müssen in Teile mit maximal 4096 Zeichen aufgeteilt und anschließend zu einer Audiodatei zusammengefügt werden. Leerzeichen und Satzzeichen zählen als Zeichen. Die Abrechnung erfolgt pro Zeichen, wobei 1 Million Zeichen 10 US-Dollar kosten.
Werden Requests gezählt?
Ja, jeder erfolgreiche Request wird für die Abrechnung erfasst. Fehlgeschlagene Requests werden nicht berechnet und das Guthaben wird vollständig erstattet. Metadaten wie Zeit, Zeichenanzahl und Status werden zur Abrechnung gespeichert. Die Abrechnung erfolgt basierend auf der tatsächlichen Zeichenanzage im Input-Feld.
Kann ich SSML verwenden?
Nein, SSML wird nicht unterstützt. Die API akzeptiert reinen Text im Input-Feld. Es gibt keine Möglichkeit, Prosodie oder Pausen über SSML-Tags zu steuern. Für präzise Steuerung müssen Sie den Text manuell anpassen oder die Geschwindigkeit und Stimme separat konfigurieren.
Gibt es ein Streaming?
Nein, es gibt kein Streaming oder WebSocket. Die API gibt die Audiodatei nach Abschluss der Synthese zurück. Für Echtzeitanwendungen müssen Sie die gesamte Datei empfangen. Die Verarbeitung erfolgt sequenziell, sodass Anfragen unter Last in einer Warteschlange stehen können.
Wie lange dauert die Antwort?
Die Generierung dauert bei langen Texten etwa Echtzeit (25 Zeichen pro Sekunde Audio). Kurze Phrasen benötigen einige Sekunden. Unter Last kann es zu Warteschlangen kommen, da Anfragen nacheinander verarbeitet werden. Die Latenz hängt von der Serverauslastung und der Textlänge ab.
Was ist bei Fehlern?
Bei Synthesefehlern wird der Betrag für die Anfrage vollständig erstattet. Sie erhalten eine Fehlermeldung im Response. Prüfen Sie die Parameter wie Stimme, Format und Textlänge. Bei anhaltenden Problemen kontaktieren Sie den Support per E-Mail. Fehlgeschlagene Requests belasten Ihr Guthaben nicht.
Kann ich die Geschwindigkeit ändern?
Ja, Sie können die Geschwindigkeit zwischen 0.25 und 4.0 einstellen. Dies wird über das Feld 'speed' im JSON-Body der Anfrage gesteuert. Der Standardwert ist 1.0. Ändern Sie diesen Wert, um die Aussprachegeschwindigkeit der Stimme anzupassen, ohne die Tonhöhe zu verändern.
Welche Formate sind verfügbar?
Verfügbare Formate sind mp3, wav, opus, flac und pcm. Wählen Sie das Format über das Feld 'response_format' in der Anfrage. mp3 ist das Standardformat für die meisten Anwendungen. Andere Formate bieten höhere Qualität oder kleinere Dateigrößen, je nach Anforderung.
Ist die API dokumentiert?
Ja, die API ist unter /docs/ dokumentiert. Die Dokumentation enthält Endpunkte, Parameterbeispiele und Fehlercodes. Die Struktur entspricht dem OpenAI Speech-Endpunkt, was die Integration erleichtert. Sie finden auch curl-Beispiele und Hinweise zur Authentifizierung direkt in der Dokumentation.
Gibt es ein Rate Limit?
Ja, das Limit beträgt 60 Anfragen pro Minute pro Schlüssel. Vor der ersten Aufladung sind es 10 Anfragen pro Minute. Bei Überschreitung werden Anfragen zurückgewiesen. Planen Sie Ihre Anfragen entsprechend, um Unterbrechungen in der Audio-Generierung zu vermeiden.
Wie rotiere ich meinen Key?
Sie können jederzeit einen neuen API-Key ausstellen. Der alte Key wird sofort ungültig, sobald der neue generiert ist. Dies geschieht über die Kontoseite nach der Anmeldung. Stellen Sie sicher, dass Ihre Anwendungen den neuen Key verwenden, bevor Sie den alten deaktivieren.
Erste Anfrage
curl
curl https://api.vz58.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.vz58.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.vz58.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 |
Authentifizierung
Der Zugang zur KlangLeser API erfolgt über einen einzelnen API-Key, der im Dashboard unter /get-api-key/ generiert wird. Dieser Schlüssel ist das einzige Authentifizierungsmerkmal für alle Requests und wird pro Site-Konto verwaltet.
API-Key erstellen
Registrieren Sie sich auf /get-api-key/ mit Google oder E-Mail. Nach der Anmeldung wird Ihr eindeutiger Bearer Token angezeigt. Notieren Sie diesen sofort, da er nur einmal sichtbar ist.
- Unterstützung für Google Sign-In und E-Mail-Passwort
- Sofortige Sichtbarkeit des Keys nach dem Login
Bearer Token verwenden
Fügen Sie den Key in den HTTP-Header Ihrer API-Anfragen ein. Das Format lautet: Authorization: Bearer tts-.... Dieser Header ist für jede Anfrage an https://api.vz58.info/v1 erforderlich.
Key rotieren
Sie können jederzeit einen neuen Key im Dashboard generieren. Sobald der neue Key aktiviert ist, wird der vorherige sofort ungültig. Dies ermöglicht eine nahtlose Aktualisierung ohne Ausfallzeit für Ihre Integrationen.
Erste Anfrage
Senden Sie Ihre erste Syntheseanfrage über das POST /v1/audio/speech-Endpunkt. Die API verarbeitet den Text und gibt das resultierende Audioformat zurück. Stellen Sie sicher, dass Ihre Eingabe die Zeichengrenzen einhält und das korrekte Authentifizierungs-Token im Header übermittelt wird.
cURL Beispiel
Nutzen Sie das folgende cURL-Kommando, um eine erste Anfrage zu testen. Ersetzen Sie tts-... durch Ihren API-Key und passen Sie den Text sowie die Stimme an.
`curl -X POST https://api.vz58.info/v1/audio/speech -H "Authorization: Bearer tts-..." -H "Content-Type: application/json" -d '{"model": "tts-1", "input": "Hallo Welt", "voice": "nova", "response_format": "mp3"}'`
JSON Body Struktur
Der JSON-Body erfordert die Felder model, input, voice und response_format. Optional können Sie speed (0.25–4.0) und language (ISO-Code) angeben. Wenn language fehlt, wird die Sprache basierend auf dem Skript erraten.
Das Feld input akzeptiert maximal 4096 Zeichen. Die Zeichenkette wird direkt in Audio umgewandelt, wobei Leerzeichen und Interpunktion als Zeichen zählen.
- model: "tts-1" oder "tts-1-hd"
- input: Der zu sprechende Text (max. 4096 Zeichen)
- voice: Einer der 8 verfügbaren Stimmen
- response_format: mp3, wav, opus, flac oder pcm
Antwort formatieren
Bei erfolgreicher Verarbeitung enthält die Antwort die Audiodaten im gewählten Format. Die Daten werden direkt im Response-Body zurückgegeben, sodass Sie diese sofort speichern oder weiterverarbeiten können.
Im Fehlerfall erhalten Sie einen HTTP-Statuscode und eine Fehlermeldung, die das Problem beschreibt. Fehlgeschlagene Anfragen werden nicht berechnet.
OpenAI SDK
Die KlangLeser API ist vollständig kompatibel mit der offiziellen OpenAI SDK für Python und JavaScript. Da das Request-Format identisch ist, müssen Sie lediglich die base_url auf https://api.vz58.info/v1 anpassen und Ihren API-Key als Bearer-Token übergeben.
Dies ermöglicht die direkte Nutzung bestehender Client-Implementierungen ohne Code-Anpassungen der Logik. Die SDKs handling von JSON-Payloads und Authentifizierung bleibt unverändert, wodurch die Integration in bestehende Text-zu-Speech-Pipelines minimiert wird.
Base URL ändern
Setzen Sie die Umgebungsvariable OPENAI_BASE_URL oder initialisieren Sie den Client explizit mit base_url="https://api.vz58.info/v1". Dies leitet alle Anfragen an den KlangLeser-Server um, während das Endpoint-Verhalten (/v1/audio/speech) gleich bleibt.
- Verwenden Sie
https://api.vz58.info/v1als Basis-URL. - Das Endpunkt-Verhalten entspricht exakt der OpenAI-Spezifikation.
Client Initialisierung
Initialisieren Sie den Client mit Ihrem API-Key im Header Authorization: Bearer tts-.... Die Parameter model, input, voice und response_format werden direkt an die API gesendet.
Stellen Sie sicher, dass Ihr SDK die neuesten JSON-Strukturen unterstützt. Die Antwort enthält die Audiodaten.
Kompatibilität prüfen
Die API unterstützt tts-1 und tts-1-hd. Beide Modelle werden vom gleichen Engine-Backend bedient. Stellen Sie sicher, dass Ihr SDK keine proprietären OpenAI-spezifischen Felder sendet, die nicht in der Standard-Spezifikation definiert sind.
Testen Sie die Verbindung mit einem kurzen Text. Bei Erfolg erhalten Sie eine Audiodatei im gewünschten Format. Bei Fehlern prüfen Sie den Header X-RateLimit-Remaining.
- Modelle:
tts-1undtts-1-hd. - Unterstützte Sprachen: 23, inklusive Deutsch und Englisch.
Modelle
Die API stellt zwei Modelle für die Text-zu-Sprache-Umwandlung bereit: tts-1 und tts-1-hd. Beide nutzen dieselbe zugrunde liegende Engine, was bedeutet, dass die Stimmqualität und Sprachfähigkeiten identisch sind. Die Wahl des Modells hängt ausschließlich von den Anforderungen an die Audioqualität und die daraus resultierenden Kosten ab.
tts-1 Eigenschaften
tts-1 ist das Standardmodell. Es liefert Audio-Dateien in etwa Echtzeitnähe aus (ca. 25 Zeichen Text pro Sekunde Audio). Für die meisten Use Cases, wie Language-Learning-Tools oder barrierefreie Inhalte, ist es ausreichend. Unter Last kann es zu Warteschlangen kommen.
- Schnelle Synthese für hohe Durchsatzraten
- Geeignet für dynamische Inhalte
- Standard-Engine für alle 8 Stimmen
tts-1-hd Eigenschaften
tts-1-hd nutzt dieselbe Engine wie tts-1, hat aber denselben Preis.
- Höhere Bitrate und Dynamik
- Natürlichere Prosodie
- Ideal für finale Produktionsinhalte
Preisunterschiede
Obwohl die Modelle unterschiedliche Qualitätsstufen repräsentieren, wird für beide dasselbe Preismodell angewendet. Der Preis beträgt 10 USD pro 1 Million Zeichen, unabhängig davon, ob tts-1 oder tts-1-hd gewählt wird. Dies vereinfacht die Kostenplanung erheblich, da der Switch zwischen den Modellen keine Preisänderung nach sich zieht.
- Einheitlicher Preis: 10 USD / 1M Zeichen
- Keine Preisdifferenz zwischen tts-1 und tts-1-hd
- Keine versteckten Kosten für HD-Audio
Formate
Das TTS-System unterstützt fünf Audioformate für die Antwort: mp3, wav, opus, flac und pcm. Die Wahl des Formats erfolgt über das Feld response_format im JSON-Body. Standardmäßig wird MP3 verwendet, was für die meisten Anwendungen ausreicht.
MP3 Ausgabe
MP3 ist das Standardformat und bietet eine gute Balance zwischen Dateigröße und Qualität. Es eignet sich ideal für Web-Integrationen und mobile Anwendungen, wo Bandbreite eine Rolle spielt.
WAV Ausgabe
WAV bietet verlustfreie Audioqualität. Dies ist vorteilhaft, wenn die Audiodateien weiter verarbeitet oder bearbeitet werden müssen, ohne dass weitere Komprimierungsartefakte hinzugefügt werden.
Andere Formate
OPUS und FLAC werden ebenfalls unterstützt. OPUS ist effizient für niedrige Bitraten, während FLAC verlustfrei komprimiert. Die Wahl hängt von den spezifischen Anforderungen Ihrer Anwendung ab.

Limits
Die API ist für zuverlässige Batch-Verarbeitung ausgelegt. Pro API-Key sind 60 Requests pro Minute erlaubt, wobei der Start mit 10 Requests pro Minute beginnt, bis der erste Top-up erfolgt ist.
Jeder Request verarbeitet maximal 4096 Zeichen. Für längere Texte müssen Sie diese entsprechend aufteilen und die Audiodateien anschließend zusammenführen.
Requests pro Minute
Der Standard-Limit beträgt 60 Requests pro Minute pro Schlüssel. Vor der ersten Aufladung des Kontos sind es 10 Requests pro Minute.
Zeichenlimit pro Request
Ein einzelner Request akzeptiert bis zu 4096 Zeichen. Leerzeichen und Interpunktion werden als Zeichen gezählt.
Warteschlange
Requests werden sequentiell verarbeitet. Bei hoher Auslastung kann es zu Wartezeiten in der Queue kommen, was die Generierungsgeschwindigkeit kurzfristig verlangsamt.
Fehler
Die API gibt klare HTTP-Statuscodes zurück, um den Erfolg oder Misserfolg der Synthese sofort erkennbar zu machen. Bei fehlendem oder ungültigem API-Key wird ein 401-Fehler ausgegeben, bei Überschreitung des Zeichenlimits (4096 Zeichen) oder der Rate-Limits (60 Requests/Minute) erhalten Sie entsprechende Hinweise.
Fehlerhafte Anfragen werden nicht berechnet. Wenn die Synthese aufgrund eines Serverfehls oder ungültiger Parameter scheitert, erhalten Sie den vollen Guthabenbetrag zurück. Dies ermöglicht eine sichere Integration in Produktionsumgebungen ohne Risiko unnötiger Kosten bei technischen Störungen.
Häufige Fehlercodes
Verwenden Sie die Statuscodes, um den Zustand Ihrer Anfrage zu prüfen. Ein 200er-Code bedeutet Erfolg, während 4xx-Fehler meist auf Client-Seite liegen (z. B. ungültiger Key oder falsches JSON-Format).
- 401 Unauthorized: API-Key fehlt oder ist ungültig.
- 429 Too Many Requests: Rate Limit von 60 Requests/Minute überschritten.
- 400 Bad Request: Ungültige Parameter oder Textlänge > 4096 Zeichen.
- 500 Internal Server Error: Vorübergehender Serverfehler (wird nicht berechnet).
Fehlerbehandlung
Prüfen Sie stets den HTTP-Statuscode vor der Verarbeitung der Audio-Daten. Bei einem 400-Fehler enthält die Response oft eine detaillierte Fehlermeldung, die das Problem präzise benennt.
Da fehlgeschlagene Requests kostenlos sind, können Sie diese sicher in Ihrer Logging-Strategie ignorieren, solange Sie das Billing korrekt tracken.
Retry-Logik
Bei 429-Fehlern (Rate Limit) sollten Sie einen exponentiellen Backoff mit Jitter anwenden. Da Requests sequenziell verarbeitet werden, kann es unter Last zu kurzen Verzögerungen kommen.
Bei 500-Fehlern ist ein sofortiger Retry oft sinnvoll, da es sich meist um transiente Fehler handelt. Wiederholen Sie den Request maximal dreimal mit abstandenen Intervallen.
Beispiele
Die folgenden Beispiele zeigen die direkte Nutzung der KlangLeser API in den gängigsten Umgebungen. Sie basieren auf der kompatiblen Struktur des OpenAI-Endpunkts und ermöglichen eine schnelle Integration in bestehende Workflows.
Alle Snippets verwenden tts-1 als Standardmodell. Ersetzen Sie tts-... durch Ihren spezifischen API-Key aus dem Dashboard.
Python Code
Nutzen Sie die offizielle OpenAI-Python-Bibliothek und passen Sie die Basis-URL an. Dies ermöglicht die Nutzung derselben Methoden, die Sie von anderen TTS-Diensten kennen.
Stellen Sie sicher, dass httpx als Transport-Backend installiert ist, falls es nicht bereits vorhanden ist.
import httpxfrom openai import OpenAIclient = OpenAI(base_url="https://api.vz58.info/v1", api_key="tts-...")
JavaScript Code
Für Node.js oder Browser-Umgebungen nutzen Sie die openai-npm-Paket. Die Konfiguration erfolgt analog zu Python durch Überschreiben der Basis-URL.
Der Aufruf von audio.speech() gibt die Audiodaten zurück.
const { OpenAI } = require('openai');const client = new OpenAI({ baseURL: 'https://api.vz58.info/v1', apiKey: 'tts-...' });
Postman Collection
Für manuelle Tests oder Integrationen ohne Code verwenden Sie Postman. Erstellen Sie eine neue POST-Anfrage an /v1/audio/speech.
Fügen Sie den Header Authorization: Bearer tts-... hinzu und setzen Sie den Body auf raw mit JSON.
Die Antwort enthält das Binärdatenableitete Audio, das Sie direkt speichern oder wiedergeben können.
Hören Sie sich die 8 Stimmen an
Jede der folgenden Samples wurde von dieser API aus demselben Satz generiert. Deutsch oder Spanisch) muss der ISO-Code explizit gesetzt werden.
23 Sprachen
Jede Stimme kann jede dieser Sprachen sprechen.
