Moknah Documentação
Comece grátis
Referência da API

Texto para Voz (TTS) em tempo real

Transmita texto progressivamente e receba bytes de áudio PCM bruto ou MP3 instantaneamente

WSS /api/v1/tts/ws/

Estabelece uma conexão WebSocket bidirecional para streaming de texto para voz em tempo real. Envie trechos de texto progressivamente (ideal para saídas de LLM) e receba fluxos de áudio binários continuamente. Os créditos são calculados de forma idêntica ao endpoint HTTP.

⚡ Otimização de latência (TTFB)

Para alcançar uma latência ultrabaixa (~200ms de Time-To-First-Byte), certifique-se de que seus trechos de texto terminem com pontuação forte (pontos ., pontos de exclamação ! ou pontos de interrogação ?). A IA armazena o texto em buffer naturalmente até detectar o limite de uma frase para garantir uma entonação humana perfeita.

Autenticação

Autentique-se usando o cabeçalho Authorization durante o handshake do WebSocket:

Authorization: Bearer YOUR_API_KEY

Configuração da conexão

Após conectar, envie uma mensagem de inicialização com a configuração desejada:

{
  "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 inicialização

Parâmetro Obrigatório Tipo Descrição
type obrigatório string Deve ser "init" para a mensagem de inicialização.
voice_id obrigatório inteiro ID da voz da lista de vozes.
output_format opcional string O formato de áudio desejado. O padrão é pcm_24000. As opções incluem:
  • 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 streaming em aplicativos com latência zero, use PCM. Para salvar arquivos, solicite MP3.
prerecording opcional inteiro 1 (normal, padrão), 2 (aprimoramento por IA / Tashkeel árabe) ou 3 (Poeta IA). Afeta o custo de créditos. 2 e 3 estão disponíveis apenas para conteúdo em árabe; consulte language.
language opcional string Idioma do conteúdo como código ISO 639-1, por exemplo ar ou en (códigos de região como ar-JO são aceitos). Define quais modos de pré-gravação são permitidos e não é enviado para a voz. Os modos 2 e 3 estão disponíveis apenas para árabe (ar). Se language for omitido, 2 e 3 implicam árabe, para que as integrações existentes continuem funcionando. Qualquer outro idioma com 2 ou 3, ou um código desconhecido, retorna uma mensagem de erro e o fluxo não é inicializado.
voice_settings opcional object Opções de personalização de voz. Veja a seção Configurações de voz abaixo.

Objeto de configurações de voz

O streaming funciona com ambos os motores em sua própria taxa por caractere, multiplicada pelo modo: emotion (padrão) e fast_mode ×1, quality e studio ×2. Vozes do motor Avançado custam ×1.5.

  • As vozes do motor Padrão são transmitidas em todos os modos: emotion (padrão, menor latência), quality e studio. O fast_mode alterna para o modelo de baixa latência.
  • As vozes do motor Avançado são transmitidas frase por frase: o áudio de cada frase começa assim que ela é concluída. Use os formatos de saída pcm_* ou mp3_* (Opus não está disponível para essas vozes).

Vozes do mecanismo Padrão

Parâmetro Tipo Intervalo Padrão Descrição
mode string emotion, quality, studio emotion Opcional. emotion (Emoção e dialeto, ×1), quality (Emoção e dialeto de qualidade, ×2) ou studio (Qualidade de estúdio, ×2). Em emotion e quality, apenas temperature e similarity se aplicam.
temperature inteiro 0 – 100 25 Mais baixo = estável e previsível, Mais alto = criativo e variado.
similarity inteiro 0 – 100 100 O quão fielmente a fala corresponde ao clone de voz original.
speed float 0.5 – 2.0 1.0 Multiplicador da velocidade de reprodução.
fast_mode inteiro 0, 1, or 2 0 1 ou 2 alterna para o modelo de baixa latência (×1 créditos) e substitui mode. 0 = desativado.

Vozes do mecanismo Avançado

Parâmetro Tipo Valores Descrição
context string até 500 caracteres O controle mais forte. Descreva o sotaque, sentimento, humor ou propósito.
setting string até 500 caracteres Cena e atmosfera.
style string neutral, warm, energetic, serious, cheerful, poetic Estilo geral de locução.
pace string slow, normal, fast Ritmo da fala.

Dica: envie frases completas (terminando com . ! ? ou uma nova linha) para obter o primeiro áudio mais rápido.

Pipeline de streaming

1. Enviar fragmentos de texto

Envie o texto progressivamente conforme seu LLM o gera:

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

O servidor processará o fragmento instantaneamente, deduzirá os créditos correspondentes a esse tamanho e começará a transmitir o áudio de volta.

2. Sinalizar conclusão (Parar)

Quando a geração de texto estiver totalmente concluída, envie o sinal de parada:

{"type": "stop"}

O servidor terminará de sintetizar o texto restante no buffer, enviará os bytes finais de áudio para você e transmitirá o sinal de fim do fluxo.

Recebimento de mensagens

O servidor envia dois tipos de quadros pelo WebSocket:

1. Fragmentos binários de áudio (PCM / MP3)

Bytes de áudio brutos transmitidos tão rápido quanto são gerados. O formato depende do output_format solicitado (o padrão é PCM de 16 bits a 24 kHz). Se você solicitou MP3, pode gravar esses bytes diretamente em um arquivo.

2. Mensagens de controle JSON

Inicialização concluída:

{"status": "ready", "message": "Inicializado e pronto para receber texto."}

Fim do fluxo (sinal de fechamento seguro):

{"type": "end_of_stream"}

Quando você recebe esta mensagem, há a garantia matemática de que 100% dos fragmentos de áudio foram entregues. Agora você pode fechar a conexão WebSocket com segurança no lado do cliente.

Erro durante a transmissão:

{"error": "Créditos insuficientes durante a transmissão"}

Exemplos prontos para produção

# 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 fechamento e erros

A conexão WebSocket pode ser fechada com um destes códigos padrão:

Código Tipo Descrição
1000 SUCCESS O fluxo foi concluído normalmente.
3011 GENERATION_ERROR A geração de áudio falhou na API de origem. Tente novamente.
4001 MISSING_API_KEY Nenhuma chave de API fornecida no cabeçalho Authorization.
4002 AUTH_FAILED Chave inválida, conta inativa, créditos iniciais insuficientes ou restrição de IP.
4290 CONCURRENT_LIMIT O usuário já possui uma conexão WebSocket de TTS ativa. O limite é de 1 por usuário.
Suporte da API

Para dúvidas ou problemas relacionados à API, entre em contato conosco em api@moknah.io.