API Dokumentation: Schnellstart & Integration

Von Klangbuch Redaktion · Aktualisiert 2026-11-19

Willkommen zur technischen Dokumentation von Klangbuch, der TTS-API für Startups, die Audiobooks und Content in Rekordzeit erstellen möchten. Hier findest du alles, was du für die nahtlose Integration in deinen Tech-Stack brauchst – egal ob du mit Python, Node.js oder Android arbeitest. Wir liefern dir präzise Referenzen zu den Endpunkten, Parametern und Antwortformaten, damit du sofort loslegen kannst.

Dieser Leitfaden richtet sich an Entwickler, die eine zuverlässige, cloudbasierte Lösung suchen, die sich einfach in bestehende Pipelines einfügt. Wir erklären dir Schritt für Schritt, wie du deinen API-Key erhältst, den ersten Request mit Curl testest und die OpenAI-SDKs anpasst. Lerne, wie du Voices konfigurierst, Rate Limits meisterst und Fehler sicher abfängst, um deine Audio-Generierung effizient zu automatisieren.

API Dokumentation: Schnellstart & Integration

Häufig gestellte Fragen

Was ist TTS?

Text-to-Speech (TTS) ist eine Technologie, die geschriebenen Text in synthetische Sprachausgabe umwandelt. Unser System verarbeitet deinen eingegebenen Text und generiert daraus eine hörbare Audiodatei, die du direkt in deine Anwendungen integrieren kannst. Die Ausgabe ist eine standardisierte Audiostruktur, die sich nahtlos in moderne Tech-Stacks einfügt.

Wie funktioniert die API?

Sende eine POST-Anfrage an https://api.vespertina.info/v1/audio/speech mit deinem JSON-Body. Das System verarbeitet die Parameter wie Modell, Text und Stimme und gibt eine Audiodatei zurück. Du kannst die offiziellen OpenAI-SDKs nutzen, indem du die base_url anpasst. Authentifizierung erfolgt über einen Bearer-Token im Header.

Welche Sprachen werden unterstützt?

Wir unterstützen 23 Sprachen: Arabisch, Chinesisch, Dänisch, Niederländisch, Englisch, Finnisch, Französisch, Deutsch, Griechisch, Hebräisch, Hindi, Italienisch, Japanisch, Koreanisch, Malaiisch, Norwegisch, Polnisch, Portugiesisch, Russisch, Spanisch, Swahili, Schwedisch und Türkisch. Jede Stimme kann jede dieser Sprachen sprechen. Wenn die Sprache nicht gesetzt ist, wird sie automatisch erraten.

Welche Stimmen gibt es?

Wir bieten 8 vordefinierte Stimmen: Aria, Nova, Luna, Sage, Felix, Milo, Atlas und Orion. Jede Stimme hat einen eigenen Klangcharakter. Die Stimmen basieren auf lizenzierten Aufnahmen aus LibriTTS-R und LibriVox. Jede generierte Datei enthält ein unsichtbares Wasserzeichen, das die synthetische Herkunft kennzeichnet.

Was kostet die API?

Der Preis beträgt 10 US-Dollar pro 1 Million Zeichen, also 0,01 USD pro 1.000 Zeichen. Leerzeichen und Interpunktion werden als Zeichen gezählt. Gescheiterte Anfragen werden kostenlos berechnet, falls die Synthese fehlschlägt. Es gibt keine monatlichen Pläne oder versteckten Gebühren. Der Kontostand verfällt nicht.

Wie hoch sind die Limits?

Du darfst 60 Anfragen pro Minute senden. Vor der ersten Aufladung sind es 10 Anfragen pro Minute. Pro Anfrage können maximal 4096 Zeichen verarbeitet werden. Bei längeren Texten müssen diese in passende Teile aufgeteilt und die Audiodateien anschließend joined werden. Die Verarbeitung erfolgt sequenziell, was bei hoher Auslastung zu Warteschlangen führen kann.

Wie funktioniert die Zahlung?

Wir akzeptieren nur USDT im TRC-20-Standard auf dem TRON-Netzwerk. Der Mindestbetrag beträgt 5 USD. Die Gutschrift erfolgt automatisch innerhalb weniger Minuten nach dem Transfer. Es gibt keine Kreditkarten, PayPal oder Rechnungen mit Mehrwertsteuer. Du kannst jederzeit einen neuen API-Schlüssel ausstellen, wodurch der alte sofort ungültig wird.

Welche Formate werden unterstützt?

Du kannst zwischen MP3, WAV, OPUS, FLAC und PCM als Ausgabeformat wählen. Diese Optionen decken die meisten technischen Anforderungen ab. Die Wahl des Formats erfolgt im JSON-Body deiner Anfrage über das Feld response_format. Das System liefert die Audiodaten direkt in der Antwort zurück, ohne sie dauerhaft zu speichern.

Werden Daten für Training genutzt?

Nein. Der eingegebene Text wird ausschließlich zur Erzeugung der Audiodatei verwendet und nicht für Trainingszwecke gespeichert. Die generierte Audiodatei wird in der Antwort zurückgegeben und ebenfalls nicht dauerhaft auf unseren Servern gespeichert. Lediglich Metadaten wie Zeit, Zeichenanzahl und Status werden für die Abrechnung aufbewahrt.

Gibt es ein kostenloses Testkonto?

Ja, du erhältst 0,50 USD Guthaben (ca. 50.000 Zeichen) für 7 Tage, wenn du dich mit Google anmeldest. Konten, die mit E-Mail und Passwort erstellt wurden, starten ohne dieses Testguthaben. Das Guthaben ist ideal, um die API-Funktionalität und die Qualität der Stimmen vor der Bezahlung zu testen.

Wie schnell ist die Generierung?

Die Generierung dauert bei langen Texten etwa Echtzeit, was ca. 25 Zeichen pro Sekunde entspricht. Bei kurzen Sätzen kann es einige Sekunden dauern. Da die Anfragen nacheinander verarbeitet werden, kann es unter Last zu Wartezeiten in der Queue kommen. Die Geschwindigkeit ist also abhängig von der Auslastung.

Kann ich eigene Stimmen hochladen?

Nein, wir bieten kein Custom Voice Cloning an. Du kannst keine eigenen Stimmen hochladen oder anpassen. Du wählst stattdessen aus unseren 8 vordefinierten Stimmen aus. Diese basieren auf lizenzierten Aufnahmen und decken verschiedene Stimmcharaktere ab.

Gibt es SSML-Unterstützung?

Nein, wir unterstützen kein SSML (Speech Synthesis Markup Language). Es gibt auch keine Phonem-Wörterbücher oder benutzerdefinierte Ausspracheregeln. Die Steuerung erfolgt ausschließlich über die Parameter für Stimme, Geschwindigkeit und Sprache im JSON-Body.

Wie funktioniert die Spracherkennung?

Dieses Produkt ist eine Text-to-Speech-API, keine Spracherkennung. Es wandelt Text in Audio um, erkennt aber keine Sprache aus Audioaufnahmen. Die Sprache wird entweder automatisch basierend auf dem Schriftbild erraten oder manuell über das language-Feld im Request gesetzt. Eine Umkehrung der Funktion ist nicht möglich.

Erste Anfrage

curl

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

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.vespertina.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.vespertina.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
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

Registriere dich auf /get-api-key/ mit Google oder E-Mail und Passwort. Nach der Anmeldung siehst du direkt deinen API-Key, das Guthaben und eine curl-Vorbereitung für den ersten Einsatz.

Google Login oder Email

Google Login oder Email

Die Registrierung dauert Sekunden. Google-Nutzer erhalten automatisch eine kostenlose Testgutschrift von 0,50 $, die sieben Tage gültig ist. E-Mail-Registerungen starten ohne Guthaben.

Ein aktiver Key pro Account

Ein aktiver Key pro Account

Pro Konto ist immer genau ein API-Key aktiv. Er wird auf der Dashboard-Seite angezeigt und kann jederzeit im Interface kopiert werden.

Neuer Key deaktiviert alten sofort

Generierst du einen neuen Key, wird der vorherige augenblicklich ungültig. Alte Requests mit dem alten Key scheitern dann sofort, was die Sicherheit erhöht.

Erster Request mit Curl

Schallwellenillustration für: Erster Request mit Curl

Um die Klangbuch API zu testen, senden Sie eine POST-Anfrage an https://api.vespertina.info/v1/audio/speech. Der Endpoint erwartet JSON-Daten, die Text, Stimme und Format definieren. Dies ist der direkteste Weg, um zu verstehen, wie die Synthese funktioniert, bevor Sie sich für eine SDK-Integration entscheiden.

Base URL und Endpoint

Die Basis-URL für alle Anfragen lautet https://api.vespertina.info/v1. Der spezifische Endpoint für die Text-zu-Sprache-Synthese ist /audio/speech. Kombinieren Sie beide zu https://api.vespertina.info/v1/audio/speech für Ihre HTTP-Anfragen.

JSON Body Struktur

Der Request Body muss JSON sein. Sie benötigen zwingend die Felder model, input und voice. Das Feld response_format ist optional; standardmäßig wird MP3 zurückgegeben. Das Textfeld input akzeptiert bis zu 4096 Zeichen. Längere Texte müssen im Client geteilt werden.

  • model: tts-1 oder tts-1-hd
  • input: Der zu sprechende Text
  • voice: z.B. aria, nova, felix
  • response_format: mp3, wav, opus, flac, pcm

Audio-Ausgabe im Terminal

Mit Curl speichern Sie die Audio-Datei direkt auf Ihrer Festplatte. Verwenden Sie das Flag -o, um die Ausgabe in eine Datei zu leiten. Der Header Content-Type gibt das Format an, das Sie empfangen. Dies ermöglicht schnelle Tests ohne Browser-Interaktion.

Integration mit OpenAI SDK

Schallwellenillustration für: Integration mit OpenAI SDK

Die API ist vollständig mit der offiziellen OpenAI-SDK-Kompatibilität ausgelegt. Du musst keine neuen Bibliotheken lernen oder komplexe Integrationslayer bauen. Ändere einfach die base_url in deinem Client auf https://api.vespertina.info/v1 und nutze dieselben Python-, Node.js- oder C#-Pakete, die du bereits kennst.

base_url anpassen

Konfiguriere deine SDK-Instanz, um die vespertina.info-Domäne als Endpoint zu nutzen. Das SDK sendet Anfragen an https://api.vesperta.info/v1 statt an die Original-Infrastruktur. Authentifizierung und Header bleiben identisch, sodass dein bestehender Code fast unverändert funktioniert.

Kompatibles Request-Format

Das JSON-Body-Format entspricht exakt dem POST /v1/audio/speech Endpunkt. Nutze die Felder model, input, voice und response_format. Da die Struktur identisch ist, können Bibliotheken, die für OpenAI TTS geschrieben wurden, direkt mit unserer Infrastruktur kommunizieren.

  • Modell: tts-1 oder tts-1-hd
  • Sprache: Optional als ISO-Code
  • Speed: 0.25 bis 4.0

Keine neuen SDKs nötig

Wir entwickeln kein eigenes SDK. Stattdessen nutzen Entwickler die etablierten OpenAI-Client-Bibliotheken. Das spart Zeit bei der Einarbeitung und garantiert, dass du aktuelle Features des SDKs direkt nutzen kannst, ohne auf eine separate Implementierung warten zu müssen.

Verfügbare Endpunkte

Schallwellenillustration für: Verfügbare Endpunkte

Die API bietet drei klare Endpunkte, um Audio-Generierung und Konfiguration nahtlos zu integrieren. Alle Anfragen erfolgen über HTTPS und nutzen JSON für die Datenübertragung, was die Anbindung an bestehende Backend-Systeme von Startups erheblich vereinfacht.

Die Struktur orientiert sich an bekannten Standards, sodass Entwickler ohne lange Einarbeitungszeit sofort produktiv sein können. Jeder Endpunkt erfüllt eine spezifische Funktion im Lebenszyklus der Audio-Erzeugung.

POST /v1/audio/speech

Dieser Endpunkt ist das Herzstück der API. Hier senden Sie Text und erhalten direkt eine Audiodatei zurück. Die Verarbeitung erfolgt serverseitig; Sie müssen keine externen Dienste orchestrieren.

Die Anfrage akzeptiert Parameter für Modell, Stimme, Format und Geschwindigkeit. Das Ergebnis ist eine binäre Audiodatei, die Sie direkt speichern oder streamen können.

  • Endpoint: POST /v1/audio/speech
  • Body: JSON mit Feldern wie 'model', 'input', 'voice'
  • Response: Audio-Binary (z.B. MP3 oder WAV)

GET /v1/voices

Nutzen Sie diesen Endpunkt, um alle verfügbaren Stimmen, Sprachen und unterstützten Formate abzurufen. Dies ist nützlich, um eine Benutzeroberfläche für die Stimmwahl dynamisch zu füllen, ohne Daten hart zu codieren.

Die Antwort enthält Metadaten zu jeder Stimme, einschließlich des zugehörigen Formats und der Sprachunterstützung.

  • Abruf der verfügbaren Stimmen
  • Informationen zu unterstützten Sprachen
  • Verfügbare Ausgabeformate

GET /v1/models

Hier erhalten Sie eine Liste der verfügbaren Modelle, aktuell 'tts-1' und 'tts-1-hd'. Beide nutzen denselben Engine-Hintergrund und Preis.

Dieser Endpunkt hilft, die korrekten Modell-IDs für Ihre API-Anfragen zu validieren und sicherzustellen, dass Ihre Integration stets aktuell bleibt.

  • Liste der aktiven Modelle
  • ID-Referenz für API-Calls
  • Preis- und Leistungsdaten

Request Parameter

Schallwellenillustration für: Request Parameter

Die API nutzt die Modelle tts-1 und tts-1-hd. Beide nutzen dieselbe Engine und haben denselben Preis. Die Wahl des Modells beeinflusst nur die interne Verarbeitung, nicht die Kosten oder die Sprachqualität signifikant für die meisten Anwendungsfälle.

Input Text Limit

Jeder Request akzeptiert maximal 4096 Zeichen. Dies umfasst alle Leerzeichen und Satzzeichen. Für längere Audiobooks oder längere Texte müssen Sie den Input manuell in passende Abschnitte aufteilen und die Audio-Dateien anschließend joinen.

Voice und Speed Einstellungen

Wählen Sie aus acht vordefinierten Stimmen, die von 23 Sprachen gesprochen werden können. Die speed-Parameter reichen von 0,25 bis 4,0. Wenn die Sprache nicht explizit über language gesetzt wird, erfolgt eine automatische Erkennung; bei lateinischem Text wird standardmäßig Englisch angenommen.

Request Parameter

Antwortformate

Schallwellenillustration für: Antwortformate

Das API gibt synthetische Audio-Dateien direkt im Response-Body zurück. Du kannst zwischen MP3, WAV, OPUS, FLAC und PCM wählen, um Dateigröße und Qualität an deinen Tech-Stack anzupassen. Die Audio-Generierung erfolgt synchron; lange Texte werden vom Client in Teile zerlegt, die Audio-Dateien werden vom Client joined und nicht intern vereint.

MP3, WAV, OPUS, FLAC, PCM

Wähle das Format, das deine Infrastruktur erfordert. MP3 ist ein gängiges Format für Web-Integration. WAV und FLAC bieten verlustlose Qualität. PCM eignet sich für direkte Audioverarbeitung, während OPUS eine effiziente Komprimierung für mobile Apps bietet.

  • MP3: Standard für Web-Integration.
  • WAV/FLAC: Verlustlose Audioqualität.
  • PCM: Rohdaten für lokale Verarbeitung.
  • OPUS: Effizientes Format.

Audio-Datei im Response

Die synthetische Sprachdatei wird direkt als binärer Inhalt im HTTP-Response zurückgegeben. Es wird kein externer Download-Link generiert, der abläuft oder gespeichert werden muss. Du empfängst die Daten sofort nach Abschluss der Synthese, was die Integration in Python, Node.js oder Android-Apps vereinfacht.

MIME-Typen beachten

Stelle sicher, dass dein Client den korrekten MIME-Typ für das gewählte Format erkennt. Dies ist entscheidend für die korrekte Wiedergabe in Browsern oder Mediaplayern. Die API sendet die Audiodaten ohne zusätzliche Metadaten, sodass die Dateigröße ausschließlich von der Textlänge und dem gewählten Format abhängt.

Fehlerbehandlung

Schallwellenillustration für: Fehlerbehandlung

HTTP Status Codes

Das API sendet klare Statuscodes wie 200 für erfolgreiche Anfragen oder 400/401/429 bei Fehlern. Ein 429-Fehler signalisiert, dass das Rate Limit von 60 Requests pro Minute (bzw. 10 vor dem ersten Top-up) überschritten wurde. In solchen Fällen wartet die Verarbeitung in einer Warteschlange, was die Latenz erhöht.

Kostenlose Requests bei Fehlern

Wenn die Synthese fehlschlägt, wird der Betrag von $0,01 pro 1.000 Zeichen vollständig erstattet. Dies gilt auch bei Netzwerkfehlern oder ungültigen Eingaben. Du zahlst also nur für erfolgreich generierte Audio-Dateien, was die Kostenplanung für Startups erheblich erleichtert.

Logik für Retry-Logik

Implementiere eine exponentielle Backoff-Strategie für Retry-Versuche bei 429- oder 500-Fehlern. Da Anfragen bei hoher Last in eine Warteschlange eingereiht werden, kann die Reaktionszeit variieren. Warte vor dem nächsten Versuch immer die angegebene Retry-After-Zeit ab, um Überlastung zu vermeiden.

Rate Limits

Schallwellenillustration für: Rate Limits

Die API begrenzt die Anfragen auf 60 Requests pro Minute pro Schlüssel. Dies stellt sicher, dass die Dienste fair und stabil für alle Nutzer bleiben, auch bei hoher Auslastung.

Vor dem ersten Top-up liegt das Limit bei 10 Requests pro Minute. Nach einer erfolgreiche Top-up über USDT (TRC-20) werden die vollen 60 Requests freigeschaltet.

60 Requests pro Minute

Jeder API-Schlüssel ist auf maximal 60 Anfragen pro Minute begrenzt. Dieses Limit gilt pro Schlüssel und wird serverseitig überwacht.

Das Limit ist ausreichend für die meisten Integrations-Szenarien, sowohl für Batch-Verarbeitungen als auch für Live-Generierungen.

  • Gilt pro API-Schlüssel
  • Berechnung pro Minute

10 Requests vor erstem Top-up

Neue Konten starten mit einem reduzierten Limit von 10 Requests pro Minute. Dies ermöglicht Tests der kostenlosen Testguthaben, ohne die Serverkapazität zu stark zu belasten.

Nach einem erfolgreichen Top-up über das TRON-Netzwerk (TRC-20) mit mindestens 5 USD steigt das Limit automatisch auf 60 Requests pro Minute.

Warteschlange bei Last

Wenn das Limit erreicht ist, werden neue Anfragen in eine Warteschlange gestellt und nacheinander abgearbeitet. Dies verhindert sofortige Fehler, verzögert aber die Antwortzeit leicht.

Lange Texte, die mehrere Teile generieren, können ebenfalls in der Warteschlange landen, wenn viele parallele Anfragen eingehen. Die Reaktionszeit bleibt jedoch vorhersehbar.

Hören Sie sich die 8 Stimmen an

Jede der folgenden Samples wurde von dieser API aus demselben Satz generiert. Dies ist besonders wichtig, wenn mehrere Requests nacheinander verarbeitet werden.

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. openai-node on GitHub
  3. TRON developer hub: TRC-20
  4. curl documentation
  5. OpenAI API reference: create speech
  6. FFmpeg documentation
  7. ISO 639 language codes
  8. Node.js documentation
  9. Tether (USDT)
  10. openai-python on GitHub
  11. W3C WAI: making audio and video accessible
  12. MDN: Web Speech API

Mehr auf dieser Website