Texto a voz (TTS) en tiempo real
Transmite texto progresivamente y recibe bytes de audio PCM sin procesar o MP3 al instante
Establece una conexión WebSocket bidireccional para transmitir texto a voz en tiempo real. Envía fragmentos de texto progresivamente (ideal para salidas de LLM) y recibe flujos de audio binarios de forma continua. Los créditos se calculan de forma idéntica al endpoint HTTP.
Para lograr una latencia ultrabaja (~200 ms de tiempo hasta el primer byte), asegúrate de que los fragmentos de texto terminen con puntuación fuerte (puntos ., signos de exclamación ! o signos de interrogación ?). La IA almacena el texto en búfer de forma natural hasta detectar el límite de una oración para garantizar una entonación humana perfecta.
Autenticación
Autentícate usando el encabezado Authorization durante el handshake de WebSocket:
Authorization: Bearer YOUR_API_KEY
Configuración de la conexión
Después de conectarte, envía un mensaje de inicialización con la configuración deseada:
{
"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
}
}
Parámetros de inicialización
| Parámetro | Obligatorio | Tipo | Descripción |
|---|---|---|---|
| type | obligatorio | string | Debe ser "init" para el mensaje de inicialización. |
| voice_id | obligatorio | entero | ID de voz de la lista de voces. |
| output_format | opcional | string | El formato de audio deseado. El valor predeterminado es pcm_24000. Las opciones incluyen:
|
| prerecording | opcional | entero | 1 (normal, predeterminado), 2 (mejora con IA / Tashkeel árabe) o 3 (Poeta IA). Afecta el costo en créditos. 2 y 3 solo están disponibles para contenido en árabe; consulta language. |
| language | opcional | string | Idioma del contenido como código ISO 639-1, por ejemplo ar o en (se aceptan códigos de región como ar-JO). Determina qué modos de pregrabación están permitidos y no se envía a la voz. Los modos 2 y 3 solo están disponibles para árabe (ar). Si se omite language, 2 y 3 implican árabe, por lo que las integraciones existentes siguen funcionando. Cualquier otro idioma con 2 o 3, o un código desconocido, devuelve un mensaje de error y el flujo no se inicializa. |
| voice_settings | opcional | object | Opciones de personalización de voz. Consulta la sección Configuración de voz a continuación. |
Objeto de configuración de voz
La transmisión funciona con ambos motores a su propia tarifa por carácter, multiplicada por el modo: emotion (predeterminado) y fast_mode ×1, quality y studio ×2. Las voces del motor Avanzado cuestan ×1.5.
- Las voces del motor Estándar se transmiten en todos los modos: emotion (predeterminado, menor latencia), quality y studio. fast_mode cambia al modelo de baja latencia.
- Las voces del motor Avanzado se transmiten oración por oración: el audio de cada oración comienza tan pronto como se completa. Usa los formatos de salida pcm_* o mp3_* (Opus no está disponible para estas voces).
Voces del motor Estándar
| Parámetro | Tipo | Rango | Predeterminado | Descripción |
|---|---|---|---|---|
| mode | string | emotion, quality, studio | emotion | Opcional. emotion (Emoción y dialecto, ×1), quality (Emoción y dialecto de calidad, ×2) o studio (Calidad de estudio, ×2). En emotion y quality solo se aplican temperature y similarity. |
| temperature | entero | 0 – 100 | 25 | Más bajo = estable y predecible, más alto = creativo y variado. |
| similarity | entero | 0 – 100 | 100 | Qué tan fielmente coincide el habla con el clon de voz original. |
| speed | float | 0.5 – 2.0 | 1.0 | Multiplicador de velocidad de reproducción. |
| fast_mode | entero | 0, 1, or 2 | 0 | 1 o 2 cambia al modelo de baja latencia (×1 créditos) y anula mode. 0 = desactivado. |
Voces del motor Avanzado
| Parámetro | Tipo | Valores | Descripción |
|---|---|---|---|
| context | string | hasta 500 caracteres | El control más potente. Describe el acento, el sentimiento, el tono o el propósito. |
| setting | string | hasta 500 caracteres | Escena y ambiente. |
| style | string | neutral, warm, energetic, serious, cheerful, poetic | Estilo general de locución. |
| pace | string | slow, normal, fast | Ritmo del habla. |
Consejo: envía oraciones completas (que terminen en . ! ? o salto de línea) para obtener el primer audio lo antes posible.
Flujo de streaming
1. Enviar fragmentos de texto
Envía el texto progresivamente a medida que tu LLM lo genera:
{"type": "text", "data": "مرحبا بكم."}
El servidor procesará el fragmento al instante, descontará los créditos correspondientes a esa longitud y comenzará a transmitir el audio de vuelta.
2. Indicar finalización (Detener)
Cuando la generación de texto haya terminado por completo, envía la señal de detención:
{"type": "stop"}
El servidor terminará de sintetizar el texto restante en su búfer, te enviará los últimos bytes de audio y emitirá la señal de fin de transmisión.
Recepción de mensajes
El servidor envía dos tipos de tramas a través del WebSocket:
1. Fragmentos de audio binarios (PCM / MP3)
Bytes de audio sin procesar transmitidos tan rápido como se generan. El formato depende del output_format solicitado (por defecto, PCM de 16 bits a 24 kHz). Si solicitaste MP3, puedes escribir estos bytes directamente en un archivo.
2. Mensajes de control JSON
Inicialización lista:
{"status": "ready", "message": "Inicializado y listo para recibir texto."}
Fin de la transmisión (señal de cierre seguro):
{"type": "end_of_stream"}
Cuando recibes este mensaje, se garantiza matemáticamente que el 100% de los fragmentos de audio han sido entregados. Ahora puedes cerrar la conexión WebSocket de forma segura desde el cliente.
Error durante la transmisión:
{"error": "Créditos insuficientes durante la transmisión"}
Ejemplos listos para producción
# 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"}
Códigos de cierre y errores
La conexión WebSocket puede cerrarse con uno de estos códigos estándar:
| Código | Tipo | Descripción |
|---|---|---|
1000 |
SUCCESS | La transmisión se completó con normalidad. |
3011 |
GENERATION_ERROR | Falló la generación de audio en la API de origen. Vuelve a intentar la solicitud. |
4001 |
MISSING_API_KEY | No se proporcionó ninguna clave API en el encabezado Authorization. |
4002 |
AUTH_FAILED | Clave no válida, cuenta inactiva, créditos iniciales insuficientes o restricción de IP. |
4290 |
CONCURRENT_LIMIT | El usuario ya tiene una conexión TTS WebSocket activa. El límite es 1 por usuario. |
Para preguntas o problemas relacionados con la API, contáctanos en api@moknah.io.