Texto para Voz (TTS) em tempo real
Transmita texto progressivamente e receba bytes de áudio PCM bruto ou MP3 instantaneamente
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.
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:
|
| 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. |
Para dúvidas ou problemas relacionados à API, entre em contato conosco em api@moknah.io.