API-Dokumentation: Nachrichten per Code vorlesen

Von ViveText Redakteursteam · Aktualisiert 2026-11-19

Diese Dokumentation erklärt, wie Sie den ViveText API-Endpunkt für die Text-to-Speech-Synthese nutzen. Wir zeigen Ihnen die Integration für Indie-Entwickler und Redaktionen, die Nachrichten oder längere Texte programmatisch in Audio umwandeln möchten. Der Aufbau orientiert sich an der bekannten OpenAI-Struktur, sodass bestehende SDKs mit einfacher Anpassung der Basis-URL funktionieren.

Sie erhalten konkrete Beispiele für cURL-Anfragen und Python-Code, erläutert zu den verfügbaren Stimmen, Sprachen und Formatoptionen. Erfahren Sie, wie Sie API-Keys generieren, Parameter wie Geschwindigkeit oder Format steuern und mit typischen Fehlerfällen wie Rate Limits umgehen. Die Anleitung ist praxisnah und direkt in Ihre Infrastruktur integrierbar.

API-Dokumentation: Nachrichten per Code vorlesen

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, Ihr Guthaben und eine curl-Vorlage. Sie können jederzeit einen neuen Key ausstellen, wobei der alte sofort ungültig wird. Jeder Account pro Website ist individuell.

Welche Parameter sind erforderlich?

Erforderlich sind model ("tts-1" oder "tts-1-hd"), input (Text bis 4096 Zeichen) und voice. Optional sind response_format, speed und language. Die Authentifizierung erfolgt über den Bearer-Token im Header. Alle anderen Felder sind frei wählbar oder werden standardmäßig gesetzt.

Wie funktioniert die Sprachauswahl?

Wählen Sie eine der 8 Stimmen. Die Sprache wird automatisch erkannt, wenn language nicht gesetzt ist. Bei lateinischem Text ohne Sprachangabe wird Englisch angenommen. Für andere Sprachen setzen Sie den ISO-Code explizit. Nicht unterstützte Sprachen wie Vietnamesisch funktionieren nicht.

Unterstützt die API SSML?

Nein, die API unterstützt kein SSML. Sie senden reinen Text, der maximal 4096 Zeichen lang sein darf. Für Pausen oder Betonungen müssen Sie die Geschwindigkeit oder die Stimme anpassen. Es gibt keine Phonem-Listen oder benutzerdefinierten Aussprachewörterbücher.

Wie hoch sind die Rate Limits?

Sie erhalten 60 Anfragen pro Minute pro Key. Vor der ersten Aufladung sind es nur 10 Anfragen pro Minute. Anfragen werden nacheinander verarbeitet. Bei hoher Last kann es zu Wartezeiten in der Queue kommen. Das Limit gilt pro API-Schlüssel.

Welche Formate werden unterstützt?

Sie können mp3, wav, opus, flac und pcm als response_format wählen. Das Audio wird direkt im Antwortkörper zurückgegeben. Es gibt kein Streaming oder WebSockets. Die Dateien enthalten einen unsichtbaren Wasserzeichen-Marker für synthetische Sprache.

Wie wird ein langer Text verarbeitet?

Teilen Sie Texte größer als 4096 Zeichen selbst in Teile auf. Senden Sie jeden Teil einzeln an die API. Verbinden Sie die zurückgegebenen Audio-Dateien anschließend zu einer einzigen Datei. Kurze Texte dauern wenige Sekunden, lange etwa Echtzeitgeschwindigkeit.

Kann ich die Geschwindigkeit ändern?

Ja, der Parameter speed akzeptiert Werte zwischen 0.25 und 4.0. Der Standardwert ist 1.0. Dies ermöglicht eine langsamere oder schnellere Sprachausgabe. Die Geschwindigkeit beeinflusst die Generierungszeit leicht, ist aber ein einfacher numerischer Wert ohne komplexe Effekte.

Was bedeutet 'tts-1-hd'?

Es handelt sich um ein Modell-Flag, das dieselbe Engine wie "tts-1" nutzt. Der Preis ist identisch. Der Unterschied liegt in der Qualität der synthetischen Stimme. Beide Modelle unterstützen alle 8 Stimmen und 23 Sprachen ohne Aufpreis.

Wie funktioniert die Authentifizierung?

Nutzen Sie den Header Authorization: Bearer tts-.... Ihr API-Schlüssel wird nach der Registrierung auf der /get-api-key/ Seite angezeigt. Jeder Account hat genau einen aktiven Schlüssel. Bei der Ausstellung eines neuen Schlüssels wird der alte sofort deaktiviert.

Wo finde ich die Liste der Stimmen?

Machen Sie einen GET-Request auf /v1/voices. Dort erhalten Sie Details zu allen verfügbaren Stimmen, Sprachen und Formaten. Auch Modelle sind unter /v1/models verfügbar. Die Liste enthält die 8 Presets wie Aria, Nova und Felix.

Wie erkenne ich Fehler in der Antwort?

Prüfen Sie den HTTP-Statuscode und den Antwortkörper. Bei Fehlern erhalten Sie eine Fehlermeldung. Gescheiterte Synthesen sind kostenlos, das Guthaben wird zurückgebucht. Erfolgreiche Requests liefern das Audio direkt. Loggen Sie Status und Zeichenanzahl für die Abrechnung.

Gibt es ein SDK für Python?

Es gibt kein eigenes SDK von uns. Nutzen Sie die offizielle OpenAI-SDK für Python. Ändern Sie einfach die base_url auf https://api.xvive.info/v1. Der Request-Body entspricht dem OpenAI-Schema. Andere Sprachen nutzen einfach HTTP-Requests.

Wie wird die Sprache automatisch erkannt?

Wenn language nicht gesetzt ist, wird die Sprache aus dem Text-Skript erkannt. Lateinische Zeichenfolgen werden standardmäßig als Englisch interpretiert. Für andere Sprachen mit lateinischer Schrift (z. B. Deutsch oder Französisch) sollte language explizit gesetzt werden.

Erste Anfrage

curl

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

Schnellstart

Schallwellenillustration für: Schnellstart

Erhalten Sie Ihren API-Schlüssel auf der Seite /get-api-key/. Nach der Registrierung mit Google oder E-Mail wird der Schlüssel sofort angezeigt. Dieser Schlüssel authentifiziert alle Anfragen an die API.

Nutzen Sie das Schlüsselformat tts-... im Authorization-Header. Für den Einstieg empfehlen wir die schnelle cURL-Lösung oder die Anpassung der OpenAI SDKs, die durch Änderung der base_url direkt mit unserer Infrastruktur arbeiten.

API-Key generieren

API-Key generieren

Registrieren Sie sich auf /get-api-key/ mit Google oder E-Mail. Der generierte Schlüssel ist sofort einsatzbereit. Sie können jederzeit einen neuen Schlüssel ausstellen, wodurch der alte sofort ungültig wird.

  • Ein aktiver Schlüssel pro Konto
  • Sofortige Wirksamkeit nach Generierung
  • Start ohne Guthaben bei E-Mail-Registrierung

Erste Anfrage mit cURL

Erste Anfrage mit cURL

Testen Sie die Integration direkt über die Konsole. Senden Sie einen POST-Request an den Speech-Endpunkt mit Ihrem Text und dem generierten Voice-Parameter.

Beispiel: `curl -X POST https://api.xvive.info/v1/audio/speech -H "Authorization: Bearer tts-..." -H "Content-Type: application/json" --data '{"model": "tts-1", "input": "Hallo Welt", "voice": "nova"}'`

OpenAI SDK Konfiguration

Da das Request-Format identisch mit dem OpenAI-Speech-Endpunkt ist, können Sie offizielle OpenAI-SDKs nutzen. Ändern Sie einfach die base_url auf https://api.xvive.info/v1 und verwenden Sie Ihren API-Schlüssel.

Dies ermöglicht eine nahtlose Integration in bestehende Python- oder Node.js-Applikationen ohne zusätzliche Client-Bibliotheken.

Endpunkte

Schallwellenillustration für: Endpunkte

Die API bietet drei klare Endpunkte für die Sprachsynthese und Metadaten. Der Speech-Endpunkt generiert Audio, während Voices und Models Strukturinformationen bereitstellen. Alle Anfragen erfolgen über HTTPS mit JSON-Body.

Speech Endpunkt (POST)

POST /v1/audio/speech verarbeitet Text und gibt Audio zurück. Das Format entspricht dem OpenAI-Standard. Sie benötigen ein Modell (tts-1 oder tts-1-hd), eine Stimme und den zu sprechenden Text.

  • Maximale Textlänge: 4096 Zeichen pro Anfrage.
  • Authentifizierung über Bearer-Token im Header.

Voices Endpunkt (GET)

GET /v1/voices listet verfügbare Stimmen, Sprachen und Formate auf. Hier prüfen Sie, welche Stimmen für Ihre Zielgruppe geeignet sind, bevor Sie die Integration starten.

  • Zeigt 8 Stimmen und 23 unterstützte Sprachen an.

Models Endpunkt (GET)

GET /v1/models zeigt die verfügbaren Modelle an. tts-1 und tts-1-hd nutzen dieselbe Engine, unterscheiden sich aber in der Qualität und Verarbeitung.

Parameter

Schallwellenillustration für: Parameter

Die API-Parameter steuern direkt Qualität und Format Ihrer Audio-Ausgabe. Mit wenigen Feldern passen Sie die Synthese exakt an den gewünschten Inhalt an.

Wählen Sie zwischen zwei Modellen, acht Stimmen und fünf Audio-Formaten. Die Einstellungen gelten pro Anfrage und sind einfach über JSON-Körper konfigurierbar.

Model Auswahl

Wählen Sie zwischen "tts-1" und "tts-1-hd". Beide nutzen denselben Engine-Standard und haben denselben Preis von 0,01 $ pro 1.000 Zeichen. Die HD-Variante bietet geringfügig höhere Audioqualität.

Voice Auswahl

Verfügbare Stimmen: aria, nova, luna, sage (weiblich); felix, milo, atlas, orion (männlich). Jede Stimme spricht alle 23 unterstützten Sprachen. Legen Sie die Sprache explizit fest, wenn der Text nicht Englisch ist.

  • aria: klarer Erzähler
  • nova: heiter, energisch
  • atlas: neutral, Nachrichten

Response Format

Wählen Sie mp3, wav, opus oder flac. PCM ist ebenfalls möglich. Die Formatwahl beeinflusst die Dateigröße und Kompatibilität; die Sprachqualität variiert je nach gewähltem Modell (tts-1 oder tts-1-hd).

Beispielanfragen

Schallwellenillustration für: Beispielanfragen

Die API erwartet JSON-Body-Payloads und gibt Audio-Dateien im Antwortkörper zurück. Die folgenden Beispiele zeigen die direkte Nutzung über cURL und veranschaulichen die Handhabung verschiedener Textlängen sowie Sprachparameter.

Kurzer Text

Ein einzelner Aufruf generiert Audio für Texte bis 4096 Zeichen. Das folgende Beispiel nutzt das Modell "tts-1" mit der Stimme "nova" und gibt die Ausgabe als MP3-Datei zurück.

```bash curl -X POST "https://api.xvive.info/v1/audio/speech" \ -H "Authorization: Bearer tts-your-api-key" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Nachricht vom 15. Mai: Markt stabil.", "voice": "nova", "response_format": "mp3"}' \ --output news.mp3 ```

Langer Text mit Split

Für längere Artikel muss die Eingabe vor der API-Nutzung in Blöcke von maximal 4096 Zeichen aufgeteilt werden. Jede Anfrage erzeugt eine separate Audiodatei.

Die generierten Dateien müssen clientseitig sequenziell aneinandergereiht werden, um den vollständigen Audioinhalt wiederherzustellen. Da die Verarbeitung seriell erfolgt, kann es unter Last zu Wartezeiten kommen.

  • Maximale Zeichenanzahl pro Request: 4096
  • Format: MP3, WAV, OPUS, FLAC oder PCM
  • End-to-End-Latenz: ca. 25 Zeichen pro Sekunde

Sprachauswahl setzen

Der Parameter language ist optional. Wird er weggelassen, versucht die API die Sprache am Skript zu erkennen. Bei lateinischem Text wird standardmäßig Englisch angenommen.

Für nicht-englische Texte im Lateinalphabet sollte language explizit gesetzt werden, um Fehlklassifikationen zu vermeiden. Die API unterstützt 23 Sprachen, darunter Deutsch, Spanisch und Japanisch.

  • Unterstützte Sprachen: Deutsch, Englisch, Französisch, Arabisch, Chinesisch und weitere
  • Nicht unterstützt: Vietnamesisch, Indonesisch, Thailändisch, Ukrainisch, Rumänisch, Tschechisch, Bengalisch

Fehlerbehandlung

Schallwellenillustration für: Fehlerbehandlung

Zuverlässige Integration erfordert das Verstehen der Fehlerquellen. Die API meldet Probleme klar zurück, damit Ihre Anwendung korrekt auf Ausfälle oder Limits reagieren kann, ohne den Nutzer zu stören.

Rate Limits

Sie erhalten maximal 60 Anfragen pro Minute pro Key. Vor der ersten Aufladung sind es nur 10 pro Minute. Bei Überschreitung antwortet die API mit Status 429 (Too Many Requests). Ihr Client sollte eine exponentielle Backoff-Logik implementieren und nicht blind weiter senden.

  • Limit: 60_req/min (post-top-up) oder 10_req/min (neu)
  • HTTP-Status: 429 Too Many Requests
  • Lösung: Exponentielles Backoff im Client

Ungültige Eingaben

Fehlerhafte Parameter führen zu einem 400-Statuscode. Prüfen Sie, ob der Text die 4096-Zeichen-Grenze nicht überschreitet und der Voice-Name existiert. Ein fehlendes Modell oder ein ungültiges Format wird sofort zurückgewiesen, ohne dass Zeichen verbraucht werden.

  • Prüfen Sie Textlänge (< 4096 Zeichen)
  • Validieren Sie Voice-IDs vor der Anfrage
  • 400 Bad Request bei fehlerhafter JSON-Struktur

Serverfehler

Ein 500-Status bedeutet, dass die Synthese im Backend fehlgeschlagen ist. Diese Anfragen werden nicht berechnet. Wiederholen Sie die Anfrage einfach. Bei anhaltenden Problemen hilft nur E-Mail-Support an [email protected].

  • Status 500: Synthesefehler
  • Kosten: 0 Zeichen (Erstattung bei Charge)
  • Support: Nur per E-Mail
Fehlerbehandlung

Sprachunterstützung

Schallwellenillustration für: Sprachunterstützung

Die API unterstützt 23 Sprachen, darunter Deutsch, Englisch, Spanisch und Französisch. Jede Stimme kann jede der unterstützten Sprachen sprechen, wodurch die Auswahl der Voice unabhängig von der Zielsprache bleibt.

ISO-Codes verwenden

Übergeben Sie den optionalen Parameter language mit dem ISO-639-1-Code (z. B. de für Deutsch, en für Englisch). Dies gewährleistet die korrekte Aussprache, insbesondere bei mehrsprachigen Inhalten oder gemischten Texten.

Automatische Erkennung

Wenn kein language-Parameter gesetzt ist, versucht die API, die Sprache basierend auf der Schriftart zu erraten. Texte in lateinischer Schrift werden standardmäßig als Englisch interpretiert. Für andere lateinische Sprachen (wie Deutsch oder Französisch) sollten Sie den Parameter explizit setzen, um Fehler zu vermeiden.

Nicht unterstützte Sprachen

Vietnamesisch, Indonesisch, Thailändisch, Ukrainisch, Rumänisch, Tschechisch, Bengalisch und weitere Sprachen werden nicht unterstützt. Wenn eine nicht erkannte Sprache in einem nicht unterstützten Sprachraum liegt, kann die Aussprache qualitativ eingeschränkt sein. Prüfen Sie vor der Integration die vollständige Liste der 23 unterstützten Sprachen.

Formatkonvertierung

Schallwellenillustration für: Formatkonvertierung

Das Format wird im Request-Parameter response_format festgelegt. Die API gibt die Audiodaten direkt im gewählten Format zurück, sodass keine nachträgliche Konvertierung im Client erforderlich ist.

MP3 Ausgabe

MP3 ist das Standardformat für die meisten Webanwendungen und bietet eine gute Balance zwischen Dateigröße und Qualität. Es wird von allen gängigen Player- und Mediateken unterstützt.

WAV Ausgabe

WAV liefert unkomprimierte Audioqualität. Dies ist nützlich, wenn weitere Verarbeitungsschritte oder eine maximale Qualität ohne Verluste erforderlich sind, was jedoch zu größeren Datenmengen führt.

OPUS & FLAC

OPUS bietet eine effiziente Komprimierung für Web-Anwendungen. FLAC stellt verlustfreie Komprimierung bereit, ideal für Archivierung oder hochwertige Wiedergabe ohne Qualitätsverlust.

Best Practices

Schallwellenillustration für: Best Practices

Effiziente Nutzung der API erfordert die Berücksichtigung der technischen Grenzen und Optimierungsmöglichkeiten. Durch das Aufteilen langer Texte und die Anpassung der Abspielgeschwindigkeit lassen sich Latenz und Kosten präzise steuern, ohne die Audioqualität zu beeinträchtigen.

Text in 4096 Zeichen splitten

Jede API-Anfrage akzeptiert maximal 4096 Zeichen im Feld input. Für längere Artikel oder Bücher müssen Sie den Text clientseitig in kleinere Blöcke zerlegen. Die API verarbeitet jede Anfrage einzeln und sequenziell, daher kann es bei hoher Last zu Warteschlangen kommen.

Audio-Dateien zusammenfügen

Da jeder Chunk eine eigene Audio-Datei zurückgibt, müssen Sie diese auf Ihrer Seite oder im Backend zu einer einzigen Datei vereinen. Für MP3-Dateien bieten sich Bibliotheken wie MP3.js an, um die Dateien nahtlos zu verketten. So entsteht ein zusammenhängendes Hörerlebnis ohne spürbare Pausen zwischen den Abschnitten.

  • Verwenden Sie Bibliotheken wie ffmpeg oder mp3-parser für das Merging.
  • Behalten Sie das gleiche response_format für alle Chunks bei.

Speed-Anpassung

Der Parameter speed im Bereich von 0.25 bis 4.0 erlaubt eine feine Abstimmung der Sprechgeschwindigkeit. Für Nachrichtenartikel ist ein Wert um 1.0 oder leicht darüber oft optimal, um Informationen schnell zu vermitteln. Niedrigere Werte eignen sich besser für komplexe Erklärungen oder Accessibility-Szenarien.

Hören Sie sich die 8 Stimmen an

Jede der folgenden Samples wurde von dieser API aus demselben Satz generiert. Die Eingabetexte werden ausschließlich zur Erzeugung der Audioausgabe verwendet und nicht für Trainingszwecke gespeichert.

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. Tether (USDT)
  3. MDN: Web Speech API
  4. IETF RFC 7845: Ogg Opus
  5. FFmpeg documentation
  6. Node.js documentation
  7. ISO 639 language codes
  8. openai-python on GitHub
  9. Creative Commons Attribution 4.0
  10. W3C WAI: making audio and video accessible
  11. LibriTTS-R paper (arXiv 2305.18802)
  12. LibriVox public-domain audiobooks

Mehr auf dieser Website