Moknah Doku
Kostenlos starten
API-Referenz

Text-zu-Sprache (TTS)

Text in natürlich klingende Sprache umwandeln

POST /api/v1/tts/generate/

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
API-Support

Bei Fragen oder Problemen rund um die API kontaktieren Sie uns unter api@moknah.io.