Schnellstart: API-Schlüssel und erste Anfrage

Von CV365 Redaktion · Aktualisiert 2026-11-19

Diese Dokumentation erläutert die Integration der WortKlang TTS-API für Produktteams in Behörden und NGOs. Sie erfahren, wie Sie Ihren API-Schlüssel generieren und erste Audioanfragen stellen. Die Anleitung fokussiert sich auf robuste, lizenzsichere Text-zu-Sprache-Lösungen mit klarer Kostentransparenz.

Sie lernen die JSON-Struktur, Authentifizierung und Parameter wie Stimme und Sprache kennen. Das Integrationsschema entspricht dem OpenAI-Standard, wodurch bestehende SDKs direkt nutzbar sind. Praktische Code-Beispiele in Python und JavaScript sowie Hinweise zu Ratenlimits und Fehlerbehandlung unterstützen Ihre technische Umsetzung.

Schnellstart: API-Schlüssel und erste Anfrage

Häufig gestellte Fragen

Wie erhalte ich einen API-Schlüssel?

Registrieren Sie sich auf /get-api-key/ mit Google oder E-Mail. Nach der Anmeldung erhalten Sie einen aktiven API-Schlüssel, der im Konto-Bereich angezeigt wird. Pro Konto ist jeweils nur ein Schlüssel aktiv. Sie können jederzeit einen neuen Schlüssel ausstellen, wodurch der alte sofort ungültig wird.

Welche Parameter sind für die API-Anfrage erforderlich?

Für die POST-Anfrage an /v1/audio/speech sind die Felder 'model' (z. B. tts-1), 'input' (der Text) und 'voice' (eine der 8 Vorgaben) erforderlich. Optional können Sie 'response_format', 'speed' und 'language' angeben. Die Authentifizierung erfolgt über den Header 'Authorization: Bearer'.

Kann ich die OpenAI SDKs verwenden?

Ja, die API verwendet dieselbe Anforderungsstruktur wie die OpenAI-Speech-Endpunkte. Offizielle OpenAI-SDKs funktionieren, wenn Sie die 'base_url' auf https://api.cv365.info/v1 ändern und Ihren API-Schlüssel verwenden. Dies ermöglicht eine schnelle Integration in bestehende Python- oder Node.js-Workflows ohne zusätzliche Bibliotheken.

Wie passe ich die base_url an?

Ändern Sie in Ihrem SDK oder HTTP-Client die Basis-URL auf https://api.cv365.info/v1. Dies ermöglicht die Nutzung der Standard-Endpunkte wie /audio/speech. Die Authentifizierung erfolgt weiterhin über den Bearer-Token-Header mit Ihrem persönlichen API-Schlüssel, der im Konto-Bereich sichtbar ist.

Welche Audioformate werden unterstützt?

Sie können 'mp3', 'wav', 'opus', 'flac' und 'pcm' als 'response_format' angeben. Jedes Format wird im Antwortkörper als Audio-Datei zurückgegeben. Die Wahl des Formats hängt von Ihren Speicher- und Wiedergabebedürfnissen ab. Jede generierte Audiodatei enthält ein unhörbares Wasserzeichen, das sie als synthetische Sprache ausweist.

Was bedeutet der Parameter 'speed'?

Der Parameter 'speed' steuert die Sprechgeschwindigkeit im Bereich von 0,25 bis 4,0. Der Standardwert entspricht der normalen Geschwindigkeit. Werte über 1,0 beschleunigen die Wiedergabe, Werte darunter verlangsamen sie. Dies ist nützlich, um Texte an verschiedene Zielgruppen oder Barrierefreiheitsstandards anzupassen.

Wie wird die Sprache automatisch erkannt?

Wenn das Feld 'language' nicht gesetzt ist, wird die Sprache anhand des Scripts erraten. Lateinischer Text wird standardmäßig als Englisch interpretiert. Für andere lateinische Sprachen oder spezifische Anforderungen sollten Sie den ISO-Code explizit setzen. Nicht unterstützte Sprachen wie Vietnamesisch werden nicht unterstützt.

Was passiert bei einem Fehler?

Bei einer fehlgeschlagenen Anfrage wird der Betrag in voller Höhe erstattet. Es erfolgt keine Belastung Ihres Kontos. Die API gibt einen Fehlerstatus zurück, sodass Sie die Anfrage bei Bedarf wiederholen können. Dies gewährleistet Kostensicherheit, auch bei technischen Problemen während der Verarbeitung.

Wie hoch ist das Zeichenlimit pro Anfrage?

Jede einzelne API-Anfrage kann maximal 4096 Zeichen im 'input'-Feld enthalten. Für längere Texte müssen Sie diese in Teile dieser Größe aufteilen und die Audio-Dateien anschließend zusammenfügen. Leerzeichen und Interpunktion zählen als Zeichen. Dies gilt für alle Modelle und Formate gleichermassen.

Werden mehrere Audioformate gleichzeitig unterstützt?

Nein, pro API-Anfrage wird genau ein 'response_format' verarbeitet. Sie müssen separate Anfragen stellen, wenn Sie das gleiche Audio in verschiedenen Formaten (z. B. MP3 und WAV) benötigen. Die Antwort enthält immer nur eine einzelne Audio-Datei im gewählten Format für die angegebene Voice.

Wie funktioniert die Authentifizierung?

Die Authentifizierung erfolgt über den HTTP-Header 'Authorization: Bearer <Ihr_Schlüssel>'. Sie erhalten Ihren Schlüssel nach der Registrierung auf /get-api-key/. Pro Konto ist jeweils nur ein Schlüssel aktiv. Bei Ausgabe eines neuen Schlüssels wird der alte sofort ungültig, was die Sicherheit erhöht.

Gibt es eine Rate Limit für Testnutzer?

Ja, es gelten 60 Anfragen pro Minute pro Schlüssel. Vor der ersten Aufladung liegt das Limit bei 10 Anfragen pro Minute. Dies gilt auch für Testnutzer mit dem kostenlosen Guthaben. Bei hoher Auslastung können Anfragen in eine Warteschlange eingereiht werden, was die Verarbeitungszeit leicht erhöht.

Kann ich den Text inChunks senden?

Die API erwartet den gesamten Text bis 4096 Zeichen in einem einzigen 'input'-Feld. Für längere Texte müssen Sie die Aufteilung und das Zusammenfügen der Audio-Dateien clientseitig implementieren. Es gibt keinen eigenen Streaming-Endpunkt. Die Authentifizierung bleibt pro Anfrage über den Bearer-Token geregelt.

Wie lange dauert die Verarbeitung?

Die Verarbeitung dauert bei langen Texten etwa Echtzeit (ca. 25 Zeichen pro Sekunde). Kurze Phrasen benötigen einige Sekunden. Anfragen werden nacheinander verarbeitet, sodass sie bei hoher Last in einer Warteschlange warten können. Die Geschwindigkeit hängt von der Textlänge ab.

Erste Anfrage

curl

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

Vorbereitung

Schallwellenillustration für: Vorbereitung

Für die Nutzung der WortKlang API ist ein aktiver API-Schlüssel erforderlich. Erstellen Sie diesen unter /get-api-key/ über Google-Anmeldung oder E-Mail. Pro Konto ist stets nur ein Schlüssel aktiv; bei Neuausstellung wird der alte sofort gesperrt.

API-Schlüssel generieren

API-Schlüssel generieren

Der Schlüssel beginnt mit "tts-" und wird im Dashboard angezeigt. Ein neuer Schlüssel kann jederzeit ausgestellt werden.

Endpunkt URL

Endpunkt URL

Alle Anfragen erfolgen an https://api.cv365.info/v1/audio/speech per POST-Methode.

Die Sprachmodelle "tts-1" und "tts-1-hd" nutzen denselben Endpunkt und Preis.

Authentifizierung

Übergeben Sie den Schlüssel im Header: "Authorization: Bearer tts-...".

Die Authentifizierung ist erforderlich, um das Kontoguthaben für die Abrechnung zu verifizieren.

  • Header: Authorization: Bearer <Ihr_Schlüssel>

Erste Anfrage

Schallwellenillustration für: Erste Anfrage

Die Interaktion mit der API erfolgt über POST-Anfragen an den Endpunkt https://api.cv365.info/v1/audio/speech. Der Body enthält die Parameter als JSON. Eine erfolgreiche Antwort liefert die Audiodaten direkt im angegebenen Format.

Curl-Beispiel

Ein minimaler Aufruf zur Generierung von Audio. Ersetzen Sie <API_KEY> durch Ihren Schlüssel und <TEXT> durch den Inhalt.

  • curl -X POST https://api.cv365.info/v1/audio/speech \\ -H "Authorization: Bearer tts-<API_KEY>" \\ -H "Content-Type: application/json" \\ -d '{"model": "tts-1", "voice": "aria", "input": "Hallo Welt", "response_format": "mp3"}'

JSON Body Struktur

Das Request-Body ist ein JSON-Objekt. Die Struktur orientiert sich an etablierten Standards, was die Integration in bestehende Systeme vereinfacht.

  • model: String (z. B. "tts-1" oder "tts-1-hd")
  • input: String (max. 4096 Zeichen)
  • voice: String (z. B. "aria", "nova")
  • response_format: String (mp3, wav, opus, flac, pcm)
  • speed: Number (optional, 0.25–4.0)
  • language: String (optional, ISO-Code)

Erforderliche Parameter

Für eine gültige Anfrage sind model, input und voice erforderlich. Ohne diese Felder lehnt die API die Verarbeitung ab und gibt einen Fehler zurück.

OpenAI SDK Integration

Schallwellenillustration für: OpenAI SDK Integration

Die API ist vollständig kompatibel mit den offiziellen OpenAI-SDKs. Durch die Anpassung der base_url auf https://api.cv365.info/v1 können bestehende Clients ohne Änderung der Logik verwendet werden. Der Authentifizierungsheader Authorization: Bearer <key> bleibt identisch.

base_url Anpassung

Initialisieren Sie das SDK mit der Endpoint-URL https://api.cv365.info/v1. Dies ermöglicht die Nutzung der vertrauten Methoden für Audio-Generierung, ohne die Request-Struktur ändern zu müssen.

Modell-Auswahl

Wählen Sie zwischen tts-1 und tts-1-hd. Beide Modelle nutzen denselben Engine-Hintergrund und die gleiche Preisstruktur. Die Auswahl erfolgt im JSON-Body über das Feld model.

  • Modellparameter: tts-1 oder tts-1-hd
  • Keine Preisunterschiede zwischen den Modellen

Code-Beispiel

Das folgende Python-Skript demonstriert die Integration unter Nutzung des OpenAI-SDKs mit dem angepassten Basis-URL-Parameter.

  • Installiere das Paket: pip install openai
  • Setze die Umgebungsvariable OPENAI_API_KEY oder übergebe sie direkt.

Parameter详解

Schallwellenillustration für: Parameter详解

Die API verarbeitet Textblöcke bis zu 4.096 Zeichen pro Aufruf. Für längere Dokumente müssen Sie den Text manuell in gültige Abschnitte aufteilen und die einzelnen Audio-Dateien anschließend zusammenführen. Leerzeichen und Satzzeichen zählen als Zeichen.

Die Stimmenauswahl erfolgt über eindeutige IDs. Jede Stimme verfügt über einen spezifischen Klangcharakter, der sich für unterschiedliche Anwendungsfälle eignet, von sachlichen Nachrichten bis hin zu narrativen Formaten.

Texteingabe (input)

Das Feld input akzeptiert Text bis zu einer Länge von 4.096 Zeichen. Bei längeren Inhalten ist eine Aufteilung in mehrere Requests erforderlich. Leerzeichen und Interpunktion werden voll als Zeichenanzahl angerechnet.

  • Maximale Länge: 4.096 Zeichen pro Request
  • Leerraum und Satzzeichen zählen zur Zeichenanzahl

Stimmen-Auswahl (voice)

Verfügbare Stimmen umfassen Aria, Nova, Luna, Sage, Felix, Milo, Atlas und Orion. Die Wahl hängt vom gewünschten Kontext ab, z.B. neutrale Nachrichten (Atlas) oder weiche Erzählstimme (Luna).

  • Aria: Warm, klar (Narration)
  • Atlas: Neutral (Nachrichten)
  • Felix: Energetisch (Promo)
  • Orion: Tief (Dokumentation)

Spracheinstellung (language)

Das optionale Feld language erwartet einen ISO-Code. Wird es weggelassen, wird die Sprache basierend auf dem Schriftbild ermittelt; Lateinische Schrift wird standardmäßig als Englisch interpretiert. Für deutsche Texte sollte de explizit gesetzt werden, da die automatische Erkennung sonst fehlschlagen kann.

  • ISO-Code notwendig für präzise Erkennung
  • Standard bei fehlender Angabe: Englisch (bei lateinischer Schrift)

Audioformate

Schallwellenillustration für: Audioformate

Die API unterstützt fünf Audioformate, die sich in Komprimierung und Dateigröße unterscheiden. Die Wahl hängt vom jeweiligen Einsatzszenario ab, ob es um Web-Streaming oder hochwertige Archivierung geht.

MP3 Unterstützung

MP3 ist das Standardformat für die meisten Integrationen. Es bietet eine gute Balance zwischen Dateigröße und Qualität, was die Übertragungsgeschwindigkeit erhöht und Speicherplatz spart.

WAV und FLAC

WAV und FLAC bieten verlustfreie Audioqualität. WAV ist weit verbreitet, während FLAC eine effizientere Komprimierung ohne Qualitätsverlust bietet. Beide Formate sind ideal für Archivzwecke oder nachgelagerte Signalverarbeitung.

OPUS und PCM

OPUS ist besonders effizient für niedrige Bandbreiten. PCM liefert rohe, unkomprimierte Daten. Jede generierte Audiodatei enthält ein unhörbares Wasserzeichen, das sie als synthetische Sprache ausweist.

Audioformate

Fehlerbehandlung

Schallwellenillustration für: Fehlerbehandlung

Die API gibt bei Validierungsfehlern den HTTP-Status 400 zurück, etwa wenn input zu lang ist oder voice ungültig ist. Bei Authentifizierungsproblemen (falscher oder fehlender Schlüssel) erfolgt eine 401-Antwort. Diese Statuscodes ermöglichen eine präzise Fehlersuche in Ihrer Integrationslogik.

Neben Statuscodes liefert die API eine strukturierte Fehlermeldung mit einer kurzen Beschreibung des Problems. Dies erleichtert die automatische Verarbeitung in Ihren Anwendungen, ohne dass manuelle Abfragen nötig sind.

HTTP Status Codes

Ein 400-Status signalisiert ein Problem mit der Eingabe, z. B. ungültige Parameter. Ein 401-Status tritt auf, wenn der API-Schl fehlende oder ungültig ist. 429 bedeutet, dass das Ratenlimit von 60 Anfragen pro Minute überschritten wurde. Diese Codes sollten von Ihrer Client-Logik direkt abgefragt werden, um den weiteren Ablauf zu steuern.

  • 400: Ungültige Anfrageparameter
  • 401: Ungültiger API-Schlüssel
  • 429: Ratenlimit überschritten

Fehlermeldungen

Die API gibt im Fehlerfall eine JSON-Antwort mit einer message-Eigenschaft zurück, die den konkreten Fehler beschreibt. Diese Nachricht ist englischsprachig und eindeutig formuliert, z. B. bei falschen Modellauswahlen oder nicht unterstützten Sprachen.

Wiederversuch-Logik

Für temporäre Fehler wie 429 (Ratenlimit) empfiehlt sich ein exponentielles Backoff-Verfahren. Da kurze Texte schnell generiert werden, aber unter Last in die Warteschlange eingereiht werden können, sollten Sie kurze Verzögerungen zwischen den Wiederholungsversuchen einplanen. Fehler bei ungültigen Parametern (400) sollten nicht automatisch wiederholt werden, da sie sich nicht durch Wiederholung beheben.

Ratenbegrenzung

Schallwellenillustration für: Ratenbegrenzung

Die API begrenzt die Anfragengeschwindigkeit auf 60 Anfragen pro Minute pro API-Schlüssel. Dies gewährleistet eine stabile Verarbeitung auch bei höheren Nutzungsvolumina in behördlichen oder NGO-Workflows. Die Begrenzung gilt pro Schlüssel und wird serverseitig überwacht.

60 Anfragen pro Minute

Nach der ersten Einzahlung ist ein Durchsatz von 60 Requests/Minute verfügbar. Für Batch-Verarbeitungen langer Texte empfiehlt sich die Aufteilung in Segmente von maximal 4096 Zeichen. Die Verarbeitung erfolgt sequentiell, sodass bei hoher Auslastung Requests in eine Warteschlange eingereiht werden können.

Limit vor der ersten Einzahlung

Bis zur ersten Top-up-Zahlung (mindestens 5 USDT) liegt das Limit bei 10 Anfragen pro Minute. Ein höheres Limit wird automatisch aktiviert, sobald die Zahlung über das TRON-Netzwerk (TRC-20) verbucht ist.

Überlastungsmanagement

Bei Überschreitung des Limits sendet die API den HTTP-Status 429 (Too Many Requests). Implementieren Sie exponentielles Backoff in Ihrer Integrationslogik, um erneute Anfragen mit zunehmenden Warteintervallen zu versuchen. Da die Synthese etwa Echtzeitgeschwindigkeit (ca. 25 Zeichen/Sekunde) erreicht, puffern Sie Audio-Dateien lokal.

  • Status 429 bei Limitüberschreitung
  • Exponentielles Backoff empfohlen
  • Sequenzielle Verarbeitung unter Last

Beispiel-Code

Schallwellenillustration für: Beispiel-Code

Diese Beispiele demonstrieren die direkte Integration in gängige Umgebungen, die für Behördensysteme und NGOs typisch sind. Sie basieren auf den offiziellen OpenAI-SDKs und erfordern keine proprietären Abhängigkeiten.

Die Skripte zeigen den standardisierten Workflow: Authentifizierung über den API-Key, Parameterübermittlung und Empfang des Audioformats. Fehler werden explizit abgefangen, um stabile Integrationen in bestehende Datenpipelines zu gewährleisten.

Python Skript

Verwenden Sie die OpenAI Python Bibliothek mit angepasstem base_url. Dies ermöglicht die direkte Nutzung bestehender Infrastruktur ohne zusätzliche Wrapper.

  • Installieren Sie openai und setzen Sie base_url auf https://api.cv365.info/v1.
  • Übergeben Sie model="tts-1", voice="sage" und input als String.
  • Speichern Sie die Antwort direkt als .mp3 Datei.

JavaScript Skript

Für Web-Integrationen nutzen Sie den Fetch-API-Aufruf oder das JS SDK. Die Struktur bleibt identisch zur Python-Variante.

  • Setzen Sie Authorization: Bearer tts-... im Header.
  • Konfigurieren Sie die Endpunkt-URL korrekt.
  • Verarbeiten Sie den Stream oder Blob direkt im Frontend.

Postman Collection

Für schnelle Tests ohne Code-Entwicklung bietet Postman eine vorkonfigurierte Sammlung. Dies ist ideal für erste Validierungen durch Product Teams.

  • Importieren Sie die JSON-Datei in Postman.
  • Legen Sie die Variable api_key im Environment ab.
  • Führen Sie den speech Endpoint aus und laden Sie die Response herunter.

Hören Sie sich die 8 Stimmen an

Jede der folgenden Samples wurde von dieser API aus demselben Satz generiert. Es wird keine SLA, Verfügbarkeitsgarantie oder Zertifizierung angeboten.

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

Mehr auf dieser Website