Moknah Documenti
Inizia gratis
Riferimento API

Sintesi vocale (TTS) in tempo reale

Invia testo in streaming progressivamente e ricevi istantaneamente byte audio PCM raw o MP3

WSS /api/v1/tts/ws/

Stabilisce una connessione WebSocket bidirezionale per lo streaming di sintesi vocale in tempo reale. Invia frammenti di testo progressivamente (ideale per gli output degli LLM) e ricevi flussi audio binari in modo continuo. I crediti vengono calcolati in modo identico all'endpoint HTTP.

⚡ Ottimizzazione della latenza (TTFB)

Per ottenere una latenza ultra-bassa (~200 ms di Time-To-First-Byte), assicurati che i frammenti di testo terminino con una punteggiatura forte (punti ., punti esclamativi ! o punti interrogativi ?). L'IA memorizza naturalmente il testo nel buffer finché non rileva la fine di una frase per garantire un'intonazione umana perfetta.

Autenticazione

Autenticati utilizzando l'header Authorization durante l'handshake WebSocket:

Authorization: Bearer YOUR_API_KEY

Configurazione della connessione

Dopo la connessione, invia un messaggio di inizializzazione con la configurazione desiderata:

{
  "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
  }
}

Parametri di inizializzazione

Parametro Obbligatorio Tipo Descrizione
type obbligatorio string Deve essere "init" per il messaggio di inizializzazione.
voice_id obbligatorio intero ID voce dalla lista delle voci.
output_format opzionale string Il formato audio desiderato. Il valore predefinito è pcm_24000. Le opzioni includono:
  • 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
Per lo streaming nelle app a latenza zero, usa PCM. Per salvare file, richiedi MP3.
prerecording opzionale intero 1 (normale, predefinito), 2 (miglioramento IA / Tashkeel arabo) o 3 (Poeta IA). Influisce sul costo in crediti. 2 e 3 sono disponibili solo per contenuti in arabo; vedi language.
language opzionale string Lingua del contenuto come codice ISO 639-1, ad esempio ar o en (sono accettati codici regionali come ar-JO). Determina quali modalità di pre-registrazione sono consentite e non viene inviata alla voce. Le modalità 2 e 3 sono disponibili solo per l'arabo (ar). Se language viene omesso, 2 e 3 implicano l'arabo, così le integrazioni esistenti continuano a funzionare. Qualsiasi altra lingua con 2 o 3, o un codice sconosciuto, restituisce un messaggio di errore e il flusso non viene inizializzato.
voice_settings opzionale object Opzioni di personalizzazione della voce. Vedi la sezione Impostazioni voce qui sotto.

Oggetto impostazioni voce

Lo streaming funziona con entrambi i motori alla propria tariffa per carattere, moltiplicata per la modalità: emotion (predefinita) e fast_mode ×1, quality e studio ×2. Le voci del motore Avanzato costano ×1,5.

  • Le voci del motore Standard vengono trasmesse in tutte le modalità: emotion (predefinita, latenza più bassa), quality e studio. fast_mode passa al modello a bassa latenza.
  • Le voci del motore Avanzato vengono trasmesse frase per frase: l'audio di ogni frase inizia non appena è completa. Usa i formati di output pcm_* o mp3_* (Opus non è disponibile per queste voci).

Voci del motore Standard

Parametro Tipo Intervallo Predefinito Descrizione
mode string emotion, quality, studio emotion Opzionale. emotion (Emozione e dialetto, ×1), quality (Emozione e dialetto di qualità, ×2) o studio (Qualità studio, ×2). In emotion e quality si applicano solo temperature e similarity.
temperature intero 0 – 100 25 Più basso = stabile e prevedibile, più alto = creativo e vario.
similarity intero 0 – 100 100 Quanto fedelmente il parlato corrisponde al clone vocale originale.
speed float 0.5 – 2.0 1.0 Moltiplicatore della velocità di riproduzione.
fast_mode intero 0, 1, or 2 0 1 o 2 passa al modello a bassa latenza (×1 crediti) e sovrascrive mode. 0 = disattivato.

Voci del motore Avanzato

Parametro Tipo Valori Descrizione
context string fino a 500 caratteri Il controllo più potente. Descrivi accento, emozione, atmosfera o scopo.
setting string fino a 500 caratteri Scena e atmosfera.
style string neutral, warm, energetic, serious, cheerful, poetic Stile di esposizione generale.
pace string slow, normal, fast Ritmo del parlato.

Consiglio: invia frasi intere (che terminano con . ! ? o a capo) per ottenere il primo audio il più velocemente possibile.

Pipeline di streaming

1. Invia frammenti di testo

Invia il testo progressivamente man mano che il tuo LLM lo genera:

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

Il server elaborerà istantaneamente il frammento, scalerà i crediti specifici per quella lunghezza e inizierà a trasmettere l'audio in risposta.

2. Segnala il completamento (Stop)

Quando la generazione del testo è completamente terminata, invia il segnale di stop:

{"type": "stop"}

Il server terminerà di sintetizzare il testo rimanente nel buffer, ti invierà gli ultimi byte audio e manderà il segnale di fine flusso (End of Stream).

Ricezione dei messaggi

Il server invia due tipi di frame tramite WebSocket:

1. Frammenti audio binari (PCM / MP3)

Byte audio grezzi trasmessi non appena vengono generati. Il formato dipende dal parametro output_format richiesto (predefinito: PCM a 16 bit a 24 kHz). Se hai richiesto MP3, puoi scrivere questi byte direttamente in un file.

2. Messaggi di controllo JSON

Inizializzazione pronta:

{"status": "ready", "message": "Inizializzato e pronto a ricevere testo."}

Fine del flusso (segnale di chiusura sicura):

{"type": "end_of_stream"}

Quando ricevi questo messaggio, hai la garanzia matematica che il 100% dei frammenti audio è stato consegnato. Ora puoi chiudere in sicurezza la connessione WebSocket lato client.

Errore durante lo streaming:

{"error": "Crediti insufficienti durante il flusso"}

Esempi pronti per la produzione

# 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"}

Codici di chiusura ed errori

La connessione WebSocket può chiudersi con uno di questi codici standard:

Codice Tipo Descrizione
1000 SUCCESS Flusso completato regolarmente.
3011 GENERATION_ERROR Generazione audio non riuscita sull'API a monte. Riprova la richiesta.
4001 MISSING_API_KEY Nessuna chiave API fornita nell'header Authorization.
4002 AUTH_FAILED Chiave non valida, account inattivo, crediti iniziali insufficienti o restrizione IP.
4290 CONCURRENT_LIMIT L'utente ha già una connessione WebSocket TTS attiva. Il limite è 1 per utente.
Supporto API

Per domande o problemi relativi all'API, contattaci all'indirizzo api@moknah.io.