Realtime tekst-naar-spraak (TTS)
Stream tekst geleidelijk en ontvang direct onbewerkte PCM- of MP3-audiobytes
Brengt een bidirectionele WebSocket-verbinding tot stand voor realtime tekst-naar-spraak-streaming. Stuur tekstfragmenten geleidelijk (ideaal voor LLM-uitvoer) en ontvang continu binaire audiostreams. Credits worden op dezelfde manier berekend als bij het HTTP-eindpunt.
Om een ultralage latentie (~200 ms Time-To-First-Byte) te bereiken, zorg je ervoor dat je tekstfragmenten eindigen met harde leestekens (punten ., uitroeptekens ! of vraagtekens ?). De AI buffert tekst op natuurlijke wijze totdat er een zinsgrens wordt gedetecteerd om een perfecte menselijke intonatie te garanderen.
Authenticatie
Authenticeer met de Authorization-header tijdens de WebSocket-handshake:
Authorization: Bearer YOUR_API_KEY
Verbindingsinstellingen
Stuur na het verbinden een initialisatiebericht met de gewenste configuratie:
{
"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
}
}
Initialisatieparameters
| Parameter | Verplicht | Type | Beschrijving |
|---|---|---|---|
| type | verplicht | string | Moet "init" zijn voor het initialisatiebericht. |
| voice_id | verplicht | geheel getal | Stem-ID uit de stemmenlijst. |
| output_format | optioneel | string | Het gewenste audioformaat. Standaard ingesteld op pcm_24000. Opties zijn onder meer:
|
| prerecording | optioneel | geheel getal | 1 (normaal, standaard), 2 (AI-verbetering / Arabische Tashkeel) of 3 (AI-dichter). Beïnvloedt de creditkosten. 2 en 3 zijn alleen beschikbaar voor Arabische content; zie language. |
| language | optioneel | string | Taal van de inhoud als ISO 639-1-code, bijvoorbeeld ar of en (regiocodes zoals ar-JO worden geaccepteerd). Dit bepaalt welke vooropnamemodi zijn toegestaan en wordt niet naar de stem gestuurd. Modus 2 en 3 zijn alleen beschikbaar voor Arabisch (ar). Als language wordt weggelaten, impliceren 2 en 3 Arabisch, zodat bestaande integraties blijven werken. Elke andere taal met 2 of 3, of een onbekende code, geeft een foutmelding terug en de stream wordt niet geïnitialiseerd. |
| voice_settings | optioneel | object | Opties voor stemaanpassing. Zie de sectie Steminstellingen hieronder. |
Steminstellingen-object
Streaming werkt met beide engines tegen een eigen tarief per teken, vermenigvuldigd met de modus: emotion (standaard) en fast_mode ×1, quality en studio ×2. Stemmen van de Geavanceerde engine kosten ×1,5.
- Stemmen van de Standaard-engine streamen in elke modus: emotion (standaard, laagste latentie), quality en studio. fast_mode schakelt over naar het model met lage latentie.
- Stemmen van de Geavanceerde engine streamen zin voor zin: de audio voor elke zin start zodra deze compleet is. Gebruik de uitvoerformaten pcm_* of mp3_* (Opus is niet beschikbaar voor deze stemmen).
Standaard-enginestemmen
| Parameter | Type | Bereik | Standaard | Beschrijving |
|---|---|---|---|---|
| mode | string | emotion, quality, studio | emotion | Optioneel. emotion (Emotie & dialect, ×1), quality (Kwaliteitsemotie & dialect, ×2) of studio (Studiokwaliteit, ×2). In emotion en quality zijn alleen temperature en similarity van toepassing. |
| temperature | geheel getal | 0 – 100 | 25 | Lager = stabiel en voorspelbaar, Hoger = creatief en gevarieerd. |
| similarity | geheel getal | 0 – 100 | 100 | Hoe nauwkeurig de spraak overeenkomt met de originele stemkloon. |
| speed | float | 0.5 – 2.0 | 1.0 | Vermenigvuldiger voor afspeelsnelheid. |
| fast_mode | geheel getal | 0, 1, or 2 | 0 | 1 of 2 schakelt naar het model met lage latentie (×1 credits) en overschrijft mode. 0 = uit. |
Geavanceerde-enginestemmen
| Parameter | Type | Waarden | Beschrijving |
|---|---|---|---|
| context | string | tot 500 tekens | De krachtigste instelling. Beschrijf accent, gevoel, sfeer of doel. |
| setting | string | tot 500 tekens | Scène en sfeer. |
| style | string | neutral, warm, energetic, serious, cheerful, poetic | Algemene spreekstijl. |
| pace | string | slow, normal, fast | Spreektempo. |
Tip: stuur volledige zinnen (eindigend op . ! ? of een nieuwe regel) voor de snelste eerste audio.
Streaming-pipeline
1. Tekstfragmenten versturen
Verstuur tekst geleidelijk terwijl je LLM deze genereert:
{"type": "text", "data": "مرحبا بكم."}
De server verwerkt het fragment direct, schrijft de specifieke credits voor die lengte af en begint met het terugstreamen van audio.
2. Voltooiing aangeven (Stop)
Wanneer het genereren van je tekst volledig is voltooid, stuur je het stopsignaal:
{"type": "stop"}
De server rondt de synthese van de resterende tekst in de buffer af, stuurt de laatste audiobytes naar je door en verzendt het End of Stream-signaal.
Berichten ontvangen
De server verstuurt twee soorten frames via de WebSocket:
1. Binaire audiofragmenten (PCM / MP3)
Ruwe audiobytes die net zo snel worden gestreamd als ze worden gegenereerd. Het formaat hangt af van het aangevraagde output_format (standaard 16-bit PCM op 24 kHz). Als je MP3 hebt aangevraagd, kun je deze bytes rechtstreeks naar een bestand schrijven.
2. JSON-controleberichten
Initialisatie gereed:
{"status": "ready", "message": "Geïnitialiseerd en klaar om tekst te ontvangen."}
Einde van stream (signaal voor veilig sluiten):
{"type": "end_of_stream"}
Wanneer je dit bericht ontvangt, is het wiskundig gegarandeerd dat 100% van de audiofragmenten is afgeleverd. Je kunt de WebSocket-verbinding nu veilig aan de clientzijde sluiten.
Fout tijdens streamen:
{"error": "Onvoldoende credits tijdens stream"}
Productieklare voorbeelden
# 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"}
Sluitcodes en fouten
De WebSocket-verbinding kan worden gesloten met een van deze standaardcodes:
| Code | Type | Beschrijving |
|---|---|---|
1000 |
SUCCESS | Stream op natuurlijke wijze voltooid. |
3011 |
GENERATION_ERROR | Audiogeneratie mislukt op de upstream-API. Probeer het verzoek opnieuw. |
4001 |
MISSING_API_KEY | Geen API-sleutel opgegeven in de Authorization-header. |
4002 |
AUTH_FAILED | Ongeldige sleutel, inactief account, onvoldoende initiële credits of IP-beperking. |
4290 |
CONCURRENT_LIMIT | Gebruiker heeft al een actieve TTS WebSocket-verbinding. De limiet is 1 per gebruiker. |
Voor vragen of problemen met betrekking tot de API kun je contact met ons opnemen via api@moknah.io.