Moknah Doku
Kostenlos starten
API-Referenz

Echtzeit-Text-zu-Sprache (TTS)

Text schrittweise streamen und sofort rohe PCM- oder MP3-Audiobytes empfangen

WSS /api/v1/tts/ws/

Stellt eine bidirektionale WebSocket-Verbindung für Echtzeit-Text-zu-Sprache-Streaming her. Senden Sie Textabschnitte schrittweise (ideal für LLM-Ausgaben) und empfangen Sie kontinuierlich binäre Audiostreams. Credits werden identisch zum HTTP-Endpunkt berechnet.

⚡ Latenzoptimierung (TTFB)

Um eine extrem niedrige Latenz (~200 ms Time-To-First-Byte) zu erreichen, stellen Sie sicher, dass Ihre Textabschnitte mit eindeutigen Satzzeichen enden (Punkte ., Ausrufezeichen ! oder Fragezeichen ?). Die KI puffert den Text automatisch, bis sie ein Satzende erkennt, um eine perfekte menschliche Intonation zu gewährleisten.

Authentifizierung

Authentifizieren Sie sich mit dem Authorization-Header während des WebSocket-Handshakes:

Authorization: Bearer YOUR_API_KEY

Verbindungseinrichtung

Senden Sie nach dem Verbinden eine Initialisierungsnachricht mit Ihrer gewünschten Konfiguration:

{
  "type": "init",
  "voice_id": 1710,
  "prerecording": 1,
  "language": "ar",
  "output_format": "pcm_24000",
  "voice_settings": {
    "temperature": 25,
    "similarity": 100,
    "expressiveness": 0,
    "speed": 1.0,
    "fast_mode": 2
  }
}

Initialisierungsparameter

Parameter Erforderlich Typ Beschreibung
type erforderlich string Muss für die Initialisierungsnachricht "init" sein.
voice_id erforderlich Integer Stimmen-ID aus der Stimmenliste.
output_format optional string Das gewünschte Audioformat. Standard ist pcm_24000. Optionen sind:
  • MP3: mp3_22050_32, 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_44100
Verwenden Sie für App-Streaming ohne Latenz PCM. Fordern Sie zum Speichern von Dateien MP3 an.
prerecording optional Integer 1 (Normal, Standard), 2 (KI-Verbesserung / Arabisches Taschkīl) oder 3 (KI-Poet). Beeinflusst die Credit-Kosten. 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. Wenn language weggelassen wird, implizieren 2 und 3 Arabisch, sodass bestehende Integrationen weiterhin funktionieren. Jede andere Sprache mit 2 oder 3 oder ein unbekannter Code gibt eine Fehlermeldung zurück und der Stream wird nicht initialisiert.
voice_settings optional object Optionen zur Stimmanpassung. Siehe Abschnitt „Stimmeinstellungen“ unten.

Stimmeinstellungsobjekt

Streaming funktioniert mit beiden Engines zum jeweiligen Zeichenpreis, multipliziert mit dem Modus: emotion (Standard) und fast_mode ×1, quality und studio ×2. Stimmen der Erweiterten Engine kosten ×1,5.

  • Stimmen der Standard-Engine streamen in jedem Modus: emotion (Standard, geringste Latenz), quality und studio. fast_mode wechselt zum Modell mit niedriger Latenz.
  • Stimmen der Erweiterten Engine werden Satz für Satz gestreamt: Das Audio für jeden Satz beginnt, sobald er vollständig ist. Verwenden Sie die Ausgabeformate pcm_* oder mp3_* (Opus ist für diese Stimmen nicht verfügbar).

Stimmen der Standard-Engine

Parameter Typ Bereich Standard Beschreibung
mode string emotion, quality, studio emotion Optional. emotion (Emotion & Dialekt, ×1), quality (Qualitäts-Emotion & Dialekt, ×2) oder studio (Studioqualität, ×2). In emotion und quality gelten nur temperature und similarity.
temperature Integer 0 – 100 25 Niedriger = stabil und vorhersehbar, Höher = kreativ und abwechslungsreich.
similarity Integer 0 – 100 100 Wie genau die Sprache mit dem ursprünglichen Stimmklon übereinstimmt.
speed float 0.5 – 2.0 1.0 Multiplikator für die Wiedergabegeschwindigkeit.
fast_mode Integer 0, 1, or 2 0 1 oder 2 wechselt zum Modell mit niedriger Latenz (×1 Credits) und überschreibt mode. 0 = aus.

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.
setting string bis zu 500 Zeichen Szene und Stimmung.
style string neutral, warm, energetic, serious, cheerful, poetic Allgemeiner Sprechstil.
pace string slow, normal, fast Sprechtempo.

Tipp: Senden Sie ganze Sätze (mit . ! ? oder Zeilenumbruch am Ende), um das erste Audio am schnellsten zu erhalten.

Streaming-Pipeline

1. Textabschnitte senden

Senden Sie Text fortlaufend, während Ihr LLM ihn generiert:

{"type": "text", "data": "مرحبا بكم."}

Der Server verarbeitet den Abschnitt sofort, zieht die entsprechenden Credits für diese Länge ab und beginnt mit dem Zurückstreamen des Audios.

2. Abschluss signalisieren (Stopp)

Wenn Ihre Textgenerierung vollständig abgeschlossen ist, senden Sie das Stoppsignal:

{"type": "stop"}

Der Server synthetisiert den verbleibenden Text im Puffer zu Ende, sendet Ihnen die letzten Audio-Bytes und schickt anschließend das Signal „End of Stream“.

Nachrichten empfangen

Der Server sendet zwei Arten von Frames über das WebSocket:

1. Binäre Audio-Abschnitte (PCM / MP3)

Rohe Audio-Bytes, die so schnell gestreamt werden, wie sie generiert werden. Das Format hängt vom angeforderten output_format ab (Standard ist 16-Bit-PCM bei 24 kHz). Wenn Sie MP3 angefordert haben, können Sie diese Bytes direkt in eine Datei schreiben.

2. JSON-Steuerungsnachrichten

Initialisierung bereit:

{"status": "ready", "message": "Initialisiert und bereit zum Empfangen von Text."}

Ende des Streams (Signal zum sicheren Schließen):

{"type": "end_of_stream"}

Wenn Sie diese Nachricht erhalten, ist mathematisch garantiert, dass 100 % der Audio-Abschnitte zugestellt wurden. Sie können die WebSocket-Verbindung nun clientseitig sicher schließen.

Fehler während des Streams:

{"error": "Unzureichende Credits während des Streams"}

Produktionsreife Beispiele

# pip install websockets
import asyncio
import websockets
import json

API_KEY = "YOUR_API_KEY"
url = "wss://api.moknah.io/api/v1/tts/ws/"

async def stream_tts():
    headers = {"Authorization": f"Bearer {API_KEY}"}
    async with websockets.connect(url, additional_headers=headers) as ws:
        # 1. Initialize session (Requesting MP3 so we can save to file)
        await ws.send(json.dumps({
            "type": "init",
            "voice_id": 1710,
            "output_format": "mp3_44100_128",
            "voice_settings": {"fast_mode": 2}
        }))
        print(f"Server: {await ws.recv()}")

        # 2. Receiver Task
        async def receive_audio():
            with open("audio.mp3", "wb") as f:
                async for msg in ws:
                    if isinstance(msg, bytes):
                        f.write(msg)
                    else:
                        data = json.loads(msg)
                        if data.get("type") == "end_of_stream":
                            print("✅ Stream finished safely.")
                            await ws.close()
                            break

        receiver = asyncio.create_task(receive_audio())

        # 3. Send Text
        for chunk in ["مرحبا بكم.", "في منصة مُكنة."]:
            await ws.send(json.dumps({"type": "text", "data": chunk}))
            await asyncio.sleep(0.5)

        # 4. Signal Stop
        await ws.send(json.dumps({"type": "stop"}))
        await receiver

asyncio.run(stream_tts())
// npm install ws
const WebSocket = require('ws');
const fs = require('fs');

const API_KEY = "YOUR_API_KEY";
const ws = new WebSocket('wss://api.moknah.io/api/v1/tts/ws/', {
    headers: { "Authorization": `Bearer ${API_KEY}` }
});

const audioStream = fs.createWriteStream('audio.mp3');

ws.on('open', function open() {
    // Requesting MP3 to safely write to an MP3 file
    ws.send(JSON.stringify({
        type: "init",
        voice_id: 1710,
        output_format: "mp3_44100_128",
        voice_settings: { fast_mode: 2 }
    }));
});

ws.on('message', function incoming(data, isBinary) {
    if (isBinary) {
        audioStream.write(data); // Save MP3 chunks
    } else {
        const msg = JSON.parse(data.toString());
        if (msg.status === 'ready') {
            console.log("Ready! Sending text...");
            ws.send(JSON.stringify({ type: "text", data: "مرحبا بكم." }));
            setTimeout(() => ws.send(JSON.stringify({ type: "text", data: "في منصة مُكة." })), 500);
            setTimeout(() => ws.send(JSON.stringify({ type: "stop" })), 1000);
        } else if (msg.type === 'end_of_stream') {
            console.log("✅ All audio received. Closing connection.");
            ws.close();
        }
    }
});
<?php
// composer require textalk/websocket
require 'vendor/autoload.php';
use WebSocket\Client;

$apiKey = "YOUR_API_KEY";
$client = new Client("wss://api.moknah.io/api/v1/tts/ws/", [
    'headers' => ['Authorization' => "Bearer $apiKey"],
    'timeout' => 60
]);

// 1. Initialize (Requesting MP3 format)
$client->text(json_encode([
    "type" => "init",
    "voice_id" => 1710,
    "output_format" => "mp3_44100_128",
    "voice_settings" => ["fast_mode" => 2]
]));
echo "Server: " . $client->receive() . "\n";

// 2. Send Text Chunks
$client->text(json_encode(["type" => "text", "data" => "مرحبا بكم."]));
$client->text(json_encode(["type" => "text", "data" => "في منصة مُكنة."]));
$client->text(json_encode(["type" => "stop"]));

// 3. Receive Audio & Control Messages
$audioFile = fopen("audio.mp3", "wb");
while (true) {
    $message = $client->receive();
    $decoded = json_decode($message, true);

    if ($decoded && isset($decoded['type']) && $decoded['type'] == 'end_of_stream') {
        echo "✅ Stream finished successfully.\n";
        break;
    } elseif (!$decoded) {
        // If it can't be decoded as JSON, it's our binary MP3 audio chunk
        fwrite($audioFile, $message);
    }
}
fclose($audioFile);
$client->close();
?>
# Standard cURL does not support bidirectional WebSockets easily.
# Use 'websocat' to test WebSockets from the command line:

websocat wss://api.moknah.io/api/v1/tts/ws/ \
  -H "Authorization: Bearer YOUR_API_KEY"

# Once connected, paste the JSON payloads interactively:
{"type": "init", "voice_id": 1710, "output_format": "mp3_44100_128"}

{"type": "text", "data": "مرحبا بكم."}

{"type": "stop"}

Schließcodes & Fehler

Die WebSocket-Verbindung kann mit einem dieser Standardcodes geschlossen werden:

Code Typ Beschreibung
1000 SUCCESS Stream regulär abgeschlossen.
3011 GENERATION_ERROR Audiogenerierung bei der Upstream-API fehlgeschlagen. Wiederholen Sie die Anfrage.
4001 MISSING_API_KEY Kein API-Schlüssel im Authorization-Header angegeben.
4002 AUTH_FAILED Ungültiger Schlüssel, inaktives Konto, unzureichende Start-Credits oder IP-Beschränkung.
4290 CONCURRENT_LIMIT Der Benutzer hat bereits eine aktive TTS-WebSocket-Verbindung. Das Limit liegt bei 1 pro Benutzer.
API-Support

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