Echtzeit-Text-zu-Sprache (TTS)
Text schrittweise streamen und sofort rohe PCM- oder MP3-Audiobytes empfangen
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.
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:
|
| 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. |
Bei Fragen oder Problemen rund um die API kontaktieren Sie uns unter api@moknah.io.