Sintesi vocale (TTS) in tempo reale
Invia testo in streaming progressivamente e ricevi istantaneamente byte audio PCM raw o MP3
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.
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:
|
| 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. |
Per domande o problemi relativi all'API, contattaci all'indirizzo api@moknah.io.