Преобразование текста в речь (TTS) в реальном времени
Передавайте текст потоком и мгновенно получайте байты аудио в формате PCM или MP3.
Устанавливает двустороннее WebSocket-соединение для потоковой передачи синтезированной речи (text-to-speech) в реальном времени. Позволяет последовательно отправлять фрагменты текста (идеально подходит для вывода LLM) и непрерывно получать бинарные аудиопотоки. Расчет кредитов производится так же, как и для HTTP-эндпоинта.
Для достижения сверхнизкой задержки (время до получения первого байта — около 200 мс) убедитесь, что фрагменты текста заканчиваются знаками завершения предложения (точкой, восклицательным или вопросительным знаком). ИИ накапливает текст в буфере до обнаружения границы предложения, чтобы обеспечить безупречную, естественную интонацию.
Аутентификация
Выполните аутентификацию с использованием заголовка Authorization во время рукопожатия WebSocket:
Authorization: Bearer YOUR_API_KEY
Настройка подключения
После подключения отправьте сообщение инициализации с желаемой конфигурацией:
{
"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
}
}
Параметры инициализации
| Параметр | Обязательно | Тип | Описание |
|---|---|---|---|
| type | обязательный | строка | Для сообщения инициализации должно быть "init". |
| voice_id | обязательный | целое число | Голосовая идентификация от список голосов. |
| output_format | по выбору | строка | Желаемый формат аудио. По умолчанию используется pcm_24000. Доступные варианты:
|
| prerecording | по выбору | целое число | 1 (обычный режим, по умолчанию), 2 (улучшение с помощью ИИ / арабская огласовка — ташкиль) или 3 (ИИ-поэт). Влияет на стоимость в кредитах. Режимы 2 и 3 доступны только для контента на арабском языке; см. параметр языка. |
| language | по выбору | строка | Язык контента в формате кода ISO 639-1, например ar или en (допускаются коды регионов, такие как ar-JO). Этот параметр определяет, какие режимы предварительной записи разрешены, и не передается голосовому движку. Режимы 2 и 3 доступны только для арабского языка (ar). Если язык не указан, режимы 2 и 3 подразумевают арабский язык, поэтому существующие интеграции продолжают работать. При использовании любого другого языка с режимами 2 или 3, а также при указании неизвестного кода, возвращается сообщение об ошибке, и поток не инициализируется. |
| voice_settings | по выбору | объект | Параметры настройки голоса. См. раздел «Настройки голоса» ниже. |
Объект настроек голоса
Потоковая передача (streaming) доступна для обоих движков по собственному тарифу за символ с учетом коэффициента режима: emotion (по умолчанию) и fast_mode — ×1, quality и studio — ×2. Голоса продвинутого движка (advanced engine) оплачиваются с коэффициентом ×1,5.
- Стандартные голоса движка доступны в потоковом режиме во всех вариантах: emotion (по умолчанию, минимальная задержка), quality и studio. Режим fast_mode переключает систему на модель с низкой задержкой.
- Голоса продвинутого движка передаются потоком по предложениям: воспроизведение аудио для каждого предложения начинается сразу после его завершения. Используйте выходные форматы pcm_* или mp3_* (формат Opus для этих голосов недоступен).
Стандартные звуки двигателя
| Параметр | Тип | Диапазон | По умолчанию | Описание |
|---|---|---|---|---|
| mode | строка | emotion, quality, studio | emotion | Опционально: emotion (эмоции и диалект, ×1), quality (качество, эмоции и диалект, ×2) или studio (студийное качество, ×2). Для режимов emotion и quality используются только параметры temperature и similarity. |
| temperature | целое число | 0 – 100 | 25 | Ниже — стабильно и предсказуемо, выше — творчески и разнообразно. |
| similarity | целое число | 0 – 100 | 100 | Насколько точно речь соответствует исходному клону голоса. |
| speed | плавать | 0.5 – 2.0 | 1.0 | Множитель скорости воспроизведения. |
| fast_mode | целое число | 0, 1, or 2 | 0 | Значение 1 или 2 переключает систему на модель с низкой задержкой (×1 кредит) и переопределяет режим. 0 = выключено. |
Улучшенное звучание двигателя
| Параметр | Тип | Ценности | Описание |
|---|---|---|---|
| context | строка | до 500 символов | Наиболее сильный способ управления. Опишите акцент, чувство, настроение или цель. |
| setting | строка | до 500 символов | Сцена и настроение. |
| style | строка | neutral, warm, energetic, serious, cheerful, poetic | Общий стиль подачи. |
| pace | строка | slow, normal, fast | Темп речи. |
Совет: отправляйте полные предложения (заканчивающиеся на . ! ? или перенос строки), чтобы быстрее получить первый аудиофрагмент.
Конвейер потоковой обработки
1. Отправка фрагментов текста
Отправляйте текст по мере его генерации вашей LLM:
{"type": "text", "data": "مرحبا بكم."}
Сервер мгновенно обработает фрагмент, спишет соответствующее количество кредитов за его длительность и начнет потоковую передачу аудио в обратном направлении.
2. Сигнал завершения (остановка)
Когда генерация текста будет полностью завершена, отправьте сигнал остановки:
{"type": "stop"}
Сервер завершит синтез оставшегося в буфере текста, передаст вам последние байты аудиоданных и отправит сигнал завершения потока.
Получение сообщений
Сервер отправляет два типа фреймов через WebSocket:
1. Бинарные фрагменты аудио (PCM / MP3)
Необработанные байты аудиоданных передаются в потоковом режиме по мере их генерации. Формат зависит от параметра `output_format` (по умолчанию используется 16-битный PCM с частотой дискретизации 24 кГц). Если выбран формат MP3, эти байты можно записывать непосредственно в файл.
2. Управляющие сообщения в формате JSON
Инициализация завершена:
{"status": "ready", "message": "Инициализировано и готово к приему текста."}
Конец потока (сигнал безопасного закрытия):
{"type": "end_of_stream"}
Получение этого сообщения гарантирует, что 100% аудиофрагментов доставлены. Теперь можно безопасно закрыть WebSocket-соединение на стороне клиента.
Ошибка в процессе передачи данных:
{"error": "Недостаточно кредитов во время трансляции"}
Примеры, готовые к промышленной эксплуатации
# 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"}
Коды закрытия и ошибки
WebSocket-соединение может закрыться с одним из следующих стандартных кодов:
| Код | Тип | Описание |
|---|---|---|
1000 |
УСПЕХ | Поток завершился естественным образом. |
3011 |
ОШИБКА_ГЕНЕРАЦИИ | Сбой генерации аудио в вышестоящем API. Повторите запрос. |
4001 |
Отсутствует API-ключ | В заголовке Authorization не указан API-ключ. |
4002 |
Сбой аутентификации | Неверный ключ, неактивная учетная запись, недостаточно начальных кредитов или ограничение по IP. |
4290 |
Ограничение на количество одновременных операций | У пользователя уже есть активное WebSocket-соединение для TTS. Лимит составляет 1 соединение на пользователя. |
По вопросам или проблемам, связанным с API, обращайтесь к нам по адресу api@moknah.io.