Moknah Documentación
Empieza gratis
Referencia de la API

Texto a voz (TTS) en tiempo real

Transmite texto progresivamente y recibe bytes de audio PCM sin procesar o MP3 al instante

WSS /api/v1/tts/ws/

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.

⚡ Optimización de latencia (TTFB)

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:
  • 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
Para transmisión en aplicaciones sin latencia, usa PCM. Para guardar archivos, solicita MP3.
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.
Soporte de API

Para preguntas o problemas relacionados con la API, contáctanos en api@moknah.io.