Moknah Docs
Gratis starten
API-referentie

Realtime tekst-naar-spraak (TTS)

Stream tekst geleidelijk en ontvang direct onbewerkte PCM- of MP3-audiobytes

WSS /api/v1/tts/ws/

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.

⚡ Latentie-optimalisatie (TTFB)

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:
  • 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
Gebruik PCM voor app-streaming zonder latentie. Vraag MP3 aan om bestanden op te slaan.
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.
API-ondersteuning

Voor vragen of problemen met betrekking tot de API kun je contact met ons opnemen via api@moknah.io.