Text-zu-Sprache (TTS)
Text in natürlich klingende Sprache umwandeln
Wandeln Sie Text mithilfe von KI-Sprachsynthese in Sprache um. Gibt eine MP3-Audiodatei zurück.
Authentifizierung
Fügen Sie Ihren API-Schlüssel im Authorization-Header hinzu.
Anfragekörper (Request Body)
| Parameter | Erforderlich | Typ | Beschreibung |
|---|---|---|---|
| text | erforderlich | string | Umzuwandelnder Text (max. 1500 Zeichen) |
| output_format | optional | string | Gewünschtes Audio-Ausgabeformat. Angegeben als codec_sampleRate_bitrate (z. B. mp3_22050_32). Standard ist mp3_44100_128. Die vollständige Liste finden Sie unten im Abschnitt „Ausgabeformate“. |
| voice_id | erforderlich | Integer | Stimmen-ID aus der Stimmenliste. |
| prerecording | optional | Integer | 1 (Basis-Optimierung), 2 (KI-Optimierung / Arabisches Taschkīl) oder 3 (KI-Poet). 2 und 3 sind nur für arabische Inhalte verfügbar; siehe language. |
| language | optional | string | Inhaltssprache als ISO-639-1-Code, zum Beispiel ar oder en (Regionscodes wie ar-JO werden akzeptiert). Sie bestimmt, welche Voraufnahmemodi zulässig sind, und wird nicht an die Stimme gesendet. Die Modi 2 und 3 sind nur für Arabisch (ar) verfügbar. Wird language weggelassen, implizieren 2 und 3 Arabisch, sodass bestehende Integrationen weiterhin funktionieren. Jede andere Sprache mit 2 oder 3 oder ein unbekannter Code gibt 400 INVALID_REQUEST mit dem Grund unter details.language zurück. |
| voice_settings | optional | String (JSON) | Optionen zur Stimmenanpassung |
Unterstützte Ausgabeformate
Der Parameter output_format kann einen der folgenden Werte annehmen:
- MP3: mp3_22050_32, mp3_24000_48, mp3_44100_32, mp3_44100_64, mp3_44100_96, mp3_44100_128, mp3_44100_192
- PCM: pcm_8000, pcm_16000, pcm_22050, pcm_24000, pcm_32000, pcm_44100, pcm_48000
- Opus: opus_48000_32, opus_48000_64, opus_48000_96, opus_48000_128, opus_48000_192
- WAV: wav_16000, wav_22050, wav_24000, wav_44100, wav_48000 — 16-Bit-Mono-WAV der direkten Engine-Ausgabe (verlustfrei). Nicht über den Streaming-WebSocket verfügbar; verwenden Sie dort pcm_*.
Dieser Abschnitt dient als Referenz, damit Benutzer das passende Format auswählen können, ohne die Hauptanfragetabelle zu überladen.
Engines & Modi
Jede Stimme gehört zu einer von zwei Engines. Die Stimmenliste gibt dies als voice_engine zurück, und die gewählte Stimme bestimmt, welche Einstellungen gelten.
Jeder API-Schlüssel gilt für eine Engine: Standard (Voreinstellung) oder erweitert, beim Erstellen des Schlüssels gewählt. Ein Schlüssel listet und nutzt nur die Stimmen seiner Engine; erstellen Sie einen zweiten Schlüssel für die andere.
- Standard-Engine (
standard) — Studiostimmen mit drei Modi, die Geschwindigkeit, Ausdruckskraft und Preis ausbalancieren. - Erweiterte Engine (
advanced, Alpha) — eigene Stimmen, die in natürlicher Sprache über context, setting, style und pace gesteuert werden. Modi finden keine Anwendung.
Modi der Standard-Engine
| mode | Name | Credits | Ideal für |
|---|---|---|---|
emotion Standard |
Emotion & Dialekt | ×1 | Schnelle, ausdrucksstarke Sprache mit Emotionen und Dialekten. Unterstützt Emotions-Tags wie [laughing] und [whispering]. |
quality |
Emotion & Dialekt in hoher Qualität | ×2 | Reichhaltigere, natürlichere Emotionen und Dialekte. Dauert etwas länger. Unterstützt Emotions-Tags. |
studio |
Studioqualität | ×2 | Klare, konsistente Studio-Sprachausgabe mit voller Stimmkontrolle. Keine Emotions-Tags. |
Anfragen ohne mode werden im Modus emotion ausgeführt.
Stimmeinstellungsobjekt
Stimmen der Standard-Engine
| Parameter | Typ | Bereich | Standard | Beschreibung |
|---|---|---|---|---|
| mode | string | emotion, quality, studio | emotion | Modus der Standard-Engine. quality und studio kosten ×2 Credits. Siehe Engines & Modi oben. |
| temperature | Integer | 0 – 100 | 25 | Steuert die Variabilität und Ausdruckskraft der Sprache. Niedrigere Werte erzeugen eine stabilere und vorhersehbarere Sprache, während höhere Werte Variation, Spontaneität und kreative Phrasierung erhöhen. |
| voice_similarity | Integer | 0 – 100 | 100 | Bestimmt, wie genau die generierte Sprache mit dem ausgewählten Stimmprofil übereinstimmt. Höhere Werte bewahren die ursprüngliche Stimmidentität, während niedrigere Werte mehr Abweichungen in Tonfall und Artikulation zulassen. |
| speed | float | 0.7 – 1.2 | 1.0 | Passt die Sprechgeschwindigkeit an. Werte unter 1.0 verlangsamen die Sprache für mehr Klarheit, während Werte über 1.0 die Sprechgeschwindigkeit erhöhen. Nur im Modus studio; wird in emotion und quality ignoriert. |
| enable_emotions veraltet | boolean | false / true | — | Wird aus Kompatibilitätsgründen noch akzeptiert, ändert aber die Ausgabe nicht mehr. Verwenden Sie stattdessen mode. |
| fast_mode veraltet | Integer | 0, 1, or 2 | — | Wird aus Kompatibilitätsgründen noch akzeptiert, ändert aber die Ausgabe nicht mehr; der Modus emotion ist bereits die schnelle Option. Verwenden Sie für Echtzeit-Audio den Streaming-Endpunkt. |
In den Modi emotion und quality sind temperature und voice_similarity die Stimmregler (jeder Wert innerhalb des Bereichs wird unverändert übernommen); speed gilt nur für den Modus studio.
Stimmen der Advanced-Engine
| Parameter | Typ | Werte | Beschreibung |
|---|---|---|---|
| context | string | bis zu 500 Zeichen | Die stärkste Steuerung. Beschreiben Sie Akzent, Gefühl, Stimmung oder Zweck, z. B. „Eine warme Dokumentarlesung in levantinischem Dialekt.“ |
| setting | string | bis zu 500 Zeichen | Szene und Stimmung, z. B. „Ein ruhiges, intimes Spätabend-Studio.“ |
| style | string | neutral, warm, energetic, serious, cheerful, poetic | Allgemeiner Sprechstil. |
| pace | string | slow, normal, fast | Sprechtempo. |
Stimmen der Advanced-Engine ignorieren mode und die Schieberegler der Standard-Engine und geben das angeforderte output_format zurück. Die Generierung kann etwas länger dauern als bei der Standard-Engine.
Regeln & Einschränkungen für Stimmeinstellungen
- Unbekannte Schlüssel, ein ungültiger Wert für mode, style oder pace oder ein context/setting mit mehr als 500 Zeichen werden mit 400 INVALID_REQUEST abgelehnt.
-
Aus Kompatibilitätsgründen dürfen die folgenden Felder nicht in voice_settings enthalten sein, wenn das veraltete enable_emotions auf true gesetzt ist:
speed,fast_mode.
Preise
Credits = Zeichen × (Basisrate + Stimmgebühr %) × Modus-Multiplikator. Der Multiplikator beträgt ×2 für quality und studio, ×1 für emotion und ×1.5 für jede Stimme der Advanced-Engine.
Beispiel
curl -X POST "https://moknah.io/api/v1/tts/generate/" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"text": "مرحبا بك في منصة مكنة",
"voice_id": 1,
"prerecording": 1,
"language": "ar",
"voice_settings": {
"mode": "emotion",
"speed": 1.0,
"temperature": 25
}
}' \
--output speech.mp3
# Advanced engine voice (voice_engine = "advanced")
curl -X POST "https://moknah.io/api/v1/tts/generate/" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"text": "مرحبا بك في منصة مكنة",
"voice_id": 2,
"voice_settings": {
"context": "A warm documentary read in a Levantine dialect.",
"pace": "slow"
}
}' \
--output speech-advanced.mp3
import requests
response = requests.post(
"https://moknah.io/api/v1/tts/generate/",
headers={
"Authorization": "Bearer your_api_key",
"Content-Type": "application/json"
},
json={
"text": "مرحبا بك في منصة مكنة",
"voice_id": 1,
"prerecording": 1,
"language": "ar",
"voice_settings": {
"mode": "emotion",
"speed": 1.0,
"temperature": 25
}
}
)
with open("speech.mp3", "wb") as f:
f.write(response.content)
const response = await fetch(
'https://moknah.io/api/v1/tts/generate/',
{
method: 'POST',
headers: {
'Authorization': 'Bearer your_api_key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
text: 'مرحبا بك في منصة مكنة',
voice_id: 1,
prerecording: 1,
language: 'ar',
voice_settings: {
mode: 'emotion',
speed: 1.0,
temperature: 25
}
})
}
);
const blob = await response.blob();
// Save or play the audio
Antwort
Gibt binäre Audiodaten im angeforderten output_format (standardmäßig MP3) mit diesen Headern zurück:
| Header | Beschreibung |
|---|---|
Content-Type |
Entspricht output_format: audio/mpeg für mp3_*, audio/ogg für opus_* (Ogg/Opus), audio/pcm;rate=N;channels=1 für pcm_* (Raw 16-Bit Little-Endian, ohne Header). |
Fehler
| Status | Code | Beschreibung |
|---|---|---|
400 |
INVALID_REQUEST | Ungültige Parameter (einschließlich unbekanntem mode, style oder pace) |
401 |
UNAUTHORIZED | Ungültiger API-Schlüssel |
402 |
INSUFFICIENT_CREDITS | Nicht genügend Credits |
429 |
RATE_LIMIT_EXCEEDED | Zu viele Anfragen |
Bei Fragen oder Problemen rund um die API kontaktieren Sie uns unter api@moknah.io.