Dokumentation: Text-to-Speech API Integration für Entwickler

Von MediStimme Redaktion · Aktualisiert 2026-11-19

Diese Dokumentation erklärt Ihnen, wie Sie die MediStimme Text-to-Speech API nahtlos in Ihre Anwendungen integrieren. Wir zeigen Schritt für Schritt, wie Sie Ihren API-Schlüssel erhalten, erste Audioanfragen mit curl testen und die Schnittstelle mit dem offiziellen OpenAI SDK verbinden. Der Fokus liegt auf klarer, einfacher Integration für Indie-Entwickler, die medizinische Texte und Patientenleitfäden effizient in hörbare Audiodateien umwandeln möchten.

Sie finden hier relevante Endpunkte und Parameter. Beispielcodes für Python und JavaScript finden Sie im Abschnitt Beispiel-Code. Die Dokumentation deckt die Unterstützung verschiedener Audioformate wie MP3 und WAV sowie die Anpassung von Stimme und Geschwindigkeit ab. Auch die Handhabung von Ratenlimits und Fehlercodes wird erläutert, damit Sie Ihre Dienste zuverlässig und ohne technische Hindernisse betreiben können.

Dokumentation: Text-to-Speech API Integration für Entwickler

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 sehen Sie Ihren persönlichen API-Schlüssel, Ihr Guthaben und die verbleibenden Zeichen. Sie können jederzeit einen neuen Schlüssel ausstellen, wodurch der alte sofort ungültig wird.

Welche Parameter sind für die Anfrage nötig?

Notwendig sind model (tts-1 oder tts-1-hd), input (Text bis 4096 Zeichen) und voice (eine der 8 Presets). Optional sind response_format, speed und language. Die Authentifizierung erfolgt über den Bearer-Token im Header.

Kann ich die API mit der OpenAI-Bibliothek nutzen?

Ja, das Request-Format ist identisch mit dem OpenAI Speech-Endpunkt. Sie können die offiziellen OpenAI-SDKs verwenden, indem Sie die base_url auf https://api.scblsg22.info/v1 ändern und Ihren API-Schlüssel hinterlegen.

Wie ändere ich die Base URL?

Ändern Sie die Base URL Ihrer Client-Konfiguration auf https://api.scblsg22.info/v1. Dies ermöglicht die direkte Nutzung der OpenAI-SDKs für unsere TTS-Endpunkte, ohne die Logik Ihrer Anwendung grundlegend ändern zu müssen.

Welche Audioformate werden unterstützt?

Sie können zwischen mp3, wav, opus, flac und pcm wählen. Das Standardformat ist mp3. Wählen Sie das Format über das Feld response_format in Ihrem JSON-Request an den Endpunkt /v1/audio/speech.

Was bedeutet das tts-1-hd Modell?

tts-1-hd ist eines der beiden verfügbaren Modelle. Es nutzt dieselbe Engine wie tts-1 und hat denselben Preis. Der Unterschied liegt in der technischen Kennzeichnung, wobei beide Modelle für medizinische Texte geeignet sind.

Wie hoch sind die Ratenlimits?

Pro API-Schlüssel sind 60 Anfragen pro Minute erlaubt. Vor der ersten Aufladung liegen die Limits bei 10 Anfragen pro Minute. Dies reicht für die meisten Indie-Entwickler aus, um Patientenleitfäden effizient zu generieren.

Was passiert bei einem Fehler?

Wenn die Synthese fehlschlägt, wird der Betrag vollständig erstattet. Sie zahlen nur für erfolgreich generierte Audiodateien. Der Fehler wird im Response-Objekt der API zurückgegeben, sodass Sie die Anfrage bei Bedarf wiederholen können.

Wie lange dauert die Generierung?

Lange Texte werden in etwa Echtzeit generiert (ca. 25 Zeichen pro Sekunde). Kurze Phrasen dauern einige Sekunden. Bei hoher Auslastung kann es zu Warteschlangen kommen, da Anfragen nacheinander verarbeitet werden.

Kann ich die Geschwindigkeit anpassen?

Ja, Sie können die Geschwindigkeit zwischen 0.25 und 4.0 einstellen. Dies ist nützlich, um medizinische Fachbegriffe klarer oder schneller darzustellen. Passen Sie den speed-Parameter im JSON-Body Ihrer Anfrage entsprechend an.

Werden die Audiodateien automatisch gespeichert?

Die generierte Audiodatei wird direkt in der Antwort zurückgegeben und nicht auf unseren Servern gespeichert. Nur Metadaten wie Zeit, Zeichenanzahl und Status werden zur Abrechnung aufbewahrt. Sie müssen die Datei selbst speichern.

Wie funktioniert die Sprachauswahl?

Legen Sie language optional fest. Ohne Angabe wird die Sprache basierend auf dem Skript erraten (Lateinisch = Englisch). Für nicht-englische Texte im Lateinischen Skript empfehlen wir die explizite Sprachangabe für bessere Ergebnisse.

Gibt es eine Dokumentation für Fehlercodes?

Standard-HTTP-Fehlercodes werden im Response zurückgegeben. Standard-HTTP-Fehlercodes werden im Response zurückgegeben. Im Fehlerfall wird der Betrag erstattet und die Fehlerursache im Response-Body beschrieben, um die Fehlersuche zu erleichtern.

Wie kann ich mehrere Stimmen testen?

Rufen Sie GET /v1/voices auf, um alle 8 Presets, Sprachen und Formate zu sehen. Testen Sie Stimmen wie Aria, Nova oder Felix direkt über POST /v1/audio/speech mit unterschiedlichen voice-Werten im JSON-Body.

Erste Anfrage

curl

curl https://api.scblsg22.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.scblsg22.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.scblsg22.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-Schlüssel erhalten

Schallwellenillustration für: API-Schlüssel erhalten

MediStimme bietet Indie-Entwicklern eine einfache Text-to-Speech-API, um medizinische Texte und Patientenleitfäden effizient in hörbare Audiodateien umzuwandeln. Der Fokus liegt auf Barrierefreiheit und klaren, natürlichen Stimmen ohne technischen Ballast.

Registrierung auf der Seite

Registrierung auf der Seite

Erstellen Sie Ihr Konto auf /get-api-key/. Sie können sich entweder mit Google oder per E-Mail und Passwort anmelden. Das Konto ist standortbezogen und ermöglicht den sofortigen Zugriff auf die API.

Nach der Anmeldung sehen Sie direkt Ihren API-Schlüssel, den Kontostand sowie verfügbare Zeichen. Bei Google-Authentifizierung erhalten Sie zusätzlich 0,50 $ Testguthaben für 50.000 Zeichen.

Schlüssel generieren

Schlüssel generieren

Jedes Konto verfügt standardmäßig über einen aktiven API-Schlüssel. Sie können jederzeit einen neuen Schlüssel generieren, wobei der alte Schlüssel sofort ungültig wird. Dies bietet Sicherheit bei der Weitergabe der Credentials.

Der Schlüssel beginnt mit "tts-" und wird im HTTP-Header als "Authorization: Bearer" verwendet.

Schlüssel verwalten

Schlüssel verwalten

Verwalten Sie Ihren Schlüssel und sehen Sie Ihren aktuellen Kontostand direkt im Dashboard. Dort finden Sie auch eine Zusammenfassung der verbrauchten Zeichen und eine Beispiel-Abfrage zum Kopieren.

Ein neuer Schlüssel stoppt den alten augenblicklich. Es gibt keine limitierte Anzahl an Schlüsseln, aber nur einer ist zur Zeit aktiv.

Erste Anfrage mit curl

Schallwellenillustration für: Erste Anfrage mit curl

Kopieren Sie das folgende Beispiel, um die API sofort zu testen. Ersetzen Sie den Platzhalter <API_KEY> mit Ihrem persönlichen Schlüssel aus dem Dashboard.

Passen Sie die Parameter an, um medizinische Begriffe korrekt auszugeben. Achten Sie darauf, dass der Text die Grenze von 4096 Zeichen nicht überschreitet.

Befehl kopieren

Nutzen Sie diesen curl-Befehl als Ausgangspunkt. Er sendet eine kurze Anweisung an die Endpunkte von MediStimme.

  • Ersetzen Sie <API_KEY> mit Ihrem Schlüssel.
  • Ändern Sie den Text im Feld input.

Parameter anpassen

Passen Sie die Stimme an, z. B. 'sage' für sachliche Anleitungen. Legen Sie das Format fest, etwa 'mp3' oder 'wav'.

Optional können Sie die Geschwindigkeit zwischen 0.25 und 4.0 anpassen, um längere Texte schneller zu verarbeiten.

Antwort analysieren

Bei Erfolg erhalten Sie eine Binärdatei. Speichern Sie diese direkt als Audiodatei.

Prüfen Sie den Statuscode 200, um sicherzustellen, dass die Synthese erfolgreich war.

Integration mit OpenAI SDK

Schallwellenillustration für: Integration mit OpenAI SDK

Die API folgt dem OpenAI-Format, sodass bestehende SDKs direkt nutzbar sind. Ändern Sie einfach die base_url auf https://api.scblsg22.info/v1 und verwenden Sie Ihren persönlichen API-Schlüssel. So funktioniert die Anbindung ohne zusätzliche Bibliotheken oder komplexe Konfigurationen.

Base URL ändern

Setzen Sie die Basis-URL in Ihrer Konfiguration auf https://api.scblsg22.info/v1. Dies ist der einzige notwendige Schritt, um die Standard-Endpunkte wie /v1/audio/speech korrekt anzusprechen.

Code anpassen

Passen Sie den Authentifizierungs-Header mit Ihrem Bearer-Token an. Die JSON-Struktur für input, voice und model bleibt identisch zu bekannten Implementierungen. Keine zusätzlichen Wrapper oder Middleware sind erforderlich.

Funktionen nutzen

Nutzen Sie alle verfügbaren Parameter wie speed oder response_format direkt. Die SDKs verarbeiten die Antwort automatisch. Sie erhalten das Audio als Binärdatei in der Antwort.

Unterstützte Formate

Schallwellenillustration für: Unterstützte Formate

Die API unterstützt sechs Audioformate, die direkt als Antwort auf Ihre Anfrage zurückgegeben werden. Die Wahl des Formats hängt von Ihrem Anwendungsfall ab: MP3 bietet eine kompakte Dateigröße, während WAV für unverarbeitete Audiodaten steht. OPUS sorgt für Effizienz und FLAC für höchste Qualität ohne Qualitätsverlust.

MP3 Ausgabe

MP3 ist das Standardformat und ideal für die Wiedergabe im Web oder in mobilen Apps. Die Datei ist klein und wird von fast allen Playern unterstützt. Für die meisten Anwendungen, wie Patientenleitfäden oder medizinische Erklärungen, ist dies die effizienteste Wahl.

WAV Ausgabe

WAV bietet unverpackte Audioqualität, was die nachträgliche Bearbeitung oder Analyse einfacher macht. Die Dateien sind jedoch deutlich größer als MP3s. Nutzen Sie dieses Format, wenn Sie die Rohdaten weiterverarbeiten oder eine verlustfreie Speicherung benötigen.

OPUS und FLAC

OPUS ist ein hochkomprimiertes Format mit sehr guter Qualität bei kleiner Dateigröße, ideal für schnelle Übertragungen. FLAC bietet verlustfreie Kompression und ist kleiner als WAV, aber größer als MP3. Beide Formate eignen sich gut, wenn Sie Platz sparen möchten, ohne Qualität zu opfern.

Parameter im Detail

Schallwellenillustration für: Parameter im Detail

Die API bietet zwei Modellvarianten, die dieselbe Engine nutzen: 'tts-1' und 'tts-1-hd'. Die Wahl des Modells ändert nichts an der Stimme, dient aber der technischen Kennzeichnung. Beide Modelle kosten gleich viel, nämlich 0,01 USD pro 1.000 Zeichen.

Die Stimmenauswahl erfolgt über acht vordefinierte Presets. Jede Stimme kann alle 23 unterstützten Sprachen sprechen. Wenn Sie keinen expliziten Sprachcode angeben, wird die Sprache basierend auf dem Textskript erraten. Bei lateinischem Text außerhalb des Englischen sollten Sie den Parameter 'language' jedoch immer explizit setzen, um falsche Erkennungen zu vermeiden.

Modellauswahl

Wählen Sie zwischen 'tts-1' und 'tts-1-hd'. Beide nutzen dieselbe Engine und haben denselben Preis. Die Unterscheidung ist rein technisch und hat keinen Einfluss auf die Audioausgabe oder die Kosten. Sie können das Modell frei wählen, da es keinen Preisnachteil oder Vorteil für die Endnutzer bedeutet.

  • Modelle: 'tts-1' oder 'tts-1-hd'
  • Preis: Identisch für beide
  • Engine: Dieselbe Synthese-Engine

Stimmeneinstellung

Wählen Sie aus acht Stimmen: Aria, Nova, Luna, Sage, Felix, Milo, Atlas oder Orion. Jede Stimme hat einen eigenen Klang, kann aber alle 23 Sprachen sprechen. Geben Sie den gewünschten Sprachcode an, wenn der Text nicht Englisch ist, um die Erkennung zu sichern.

Die Stimmen basieren auf lizenzierten Aufnahmen. Jede Audioausgabe enthält einen unsichtbaren Wasserzeichen-Hinweis auf synthetische Sprache. Es gibt keine SSML-Unterstützung, die Stimmfarbe bleibt konstant.

  • 8 Presets: Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion
  • Alle Stimmen sprechen alle 23 Sprachen
  • Sprachcode 'language' bei Nicht-Englisch empfohlen

Geschwindigkeitsanpassung

Passen Sie die Sprechgeschwindigkeit mit dem Parameter 'speed' an. Der Wertebereich reicht von 0,25 (halbe Geschwindigkeit) bis 4,0 (vierfache Geschwindigkeit). Dies ist nützlich, um Patientenleitfäden an verschiedene Hörbedürfnisse anzupassen oder die Generierungszeit bei langen Texten leicht zu beeinflussen.

Kürzere Phrasen dauern einige Sekunden, längere Texte werden etwa in Echtzeit generiert (ca. 25 Zeichen pro Sekunde). Die Geschwindigkeit ändert nichts an der Qualität der Synthese, nur an der Dauer der Audiodatei.

  • Wertebereich: 0,25 bis 4,0
  • Standardgeschwindigkeit: 1,0
  • Keine Qualitätsänderung durch Geschwindigkeit

Fehlerbehandlung

Schallwellenillustration für: Fehlerbehandlung

Bei der Nutzung der API können verschiedene Fehler auftreten, die meist schnell zu lösen sind. Ein häufiges Problem ist das Überschreiten der Ratenlimits, insbesondere wenn neue Konten noch nicht aufgeladen wurden.

Die Fehlercodes helfen dabei, die Ursache zu identifizieren, sei es ein ungültiger API-Schlüssel oder ein Formatierungsfehler im Request.

Häufige Fehlercodes

Die API gibt klare HTTP-Statuscodes zurück. Bei ungültigen Schlüsseln oder fehlenden Parametern erhalten Sie Fehlermeldungen, die direkt in der Antwort enthalten sind.

Fehlerhafte Texteingaben (z. B. zu lang) werden sofort erkannt, bevor die Synthese beginnt.

  • 401: Ungültiger oder fehlender API-Schlüssel
  • 400: Falsche Parameter oder Formatfehler
  • 429: Ratenlimit überschritten

Ratenlimits

Pro API-Schlüssel sind 60 Anfragen pro Minute erlaubt. Vor dem ersten Aufladen beträgt das Limit nur 10 Anfragen pro Minute.

Dieses Limit ist wichtig, um die Serverlast zu steuern und die Qualität der Synthese sicherzustellen.

  • Standardlimit: 60 Anfragen/Minute
  • Neue Konten: 10 Anfragen/Minute
  • Limit steigt nach Top-up

Zeitüberschreitungen

Bei hoher Auslastung kann es zu Wartezeiten in der Queue kommen. Lange Texte benötigen mehr Verarbeitungszeit.

Stellen Sie sicher, dass Ihre Client-Anwendung auf Timeout reagiert, um keine unnötigen Requests zu senden.

Ratenlimits

Schallwellenillustration für: Ratenlimits

Die API erlaubt 60 Anfragen pro Minute pro API-Schlüssel. Dies reicht für die meisten Anwendungsfälle aus, da kurze Texte in Sekunden verarbeitet werden. Längere Texte werden automatisch in Abschnitte unterteilt.

60 Anfragen pro Minute

Jeder aktive API-Schlüssel ist auf 60 Requests pro Minute begrenzt. Da die Synthese nacheinander verarbeitet wird, kann es unter Last zu Warteschlangen kommen. Für die meisten Indie-Entwickler ist dieses Limit ausreichend, um medizinische Texte effizient zu generieren.

Begrenzung nach Registrierung

Neue Konten starten mit einem reduzierten Limit von 10 Anfragen pro Minute. Dies gilt, bis die erste Aufladung erfolgreich verbucht wurde. Dieser Schritt dient der Verhinderung von Missbrauch bei kostenlosen Testkonten.

Aufladung erhöht Limit

Nach dem ersten Top-up über USDT (TRC-20) aktiviert sich das volle Limit von 60 Anfragen pro Minute sofort. Das Limit gilt pro Schlüssel, nicht pro Konto. Ein neuer Schlüssel kann jederzeit ausgestellt werden, wobei der alte sofort ungült wird.

Beispiel-Code

Schallwellenillustration für: Beispiel-Code

Die Integration von MediStimme ist dank der kompatiblen Struktur mit der OpenAI-API einfach. Der folgende Code zeigt, wie Sie Text direkt in Audiodateien konvertieren.

Python Beispiel

Nutzen Sie die offizielle OpenAI-SDK für Python. Ändern Sie die base_url auf https://api.scblsg22.info/v1 und setzen Sie Ihren API-Schlüssel. Der Code sendet den Text an den Endpunkt /v1/audio/speech und speichert die Audioantwort lokal.

  • Installieren Sie das OpenAI-Python-Paket.
  • Setzen Sie base_url korrekt.
  • Speichern Sie die binäre Antwort als .mp3-Datei.

JavaScript Beispiel

Im Browser oder Node.js nutzen Sie fetch. Senden Sie einen POST-Request an https://api.scblsg22.info/v1/audio/speech mit dem Header Authorization: Bearer YOUR_KEY. Lesen Sie den Response-Stream aus, um die Audiodatei zu erhalten.

  • Verwenden Sie fetch mit method: 'POST'.
  • Setzen Sie Authorization Header.
  • Konvertieren Sie den Blob in ein Audio-Objekt.

Konfiguration

Passen Sie die Parameter voice, model und response_format an Ihre Bedürfnisse an. Für medizinische Texte ist die Stimme sage eine gute Wahl. Die Geschwindigkeit kann zwischen 0.25 und 4.0 eingestellt werden.

Hören Sie sich die 8 Stimmen an

Jede der folgenden Samples wurde von dieser API aus demselben Satz generiert. Dies ist besonders hilfreich für ältere Patienten oder Menschen mit Sehbehinderungen.

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

Mehr auf dieser Website