Moknah Документы
Начать бесплатно
Справочник по API

Преобразование текста в речь (TTS) в реальном времени

Передавайте текст потоком и мгновенно получайте байты аудио в формате PCM или MP3.

WSS /api/v1/tts/ws/

Устанавливает двустороннее WebSocket-соединение для потоковой передачи синтезированной речи (text-to-speech) в реальном времени. Позволяет последовательно отправлять фрагменты текста (идеально подходит для вывода LLM) и непрерывно получать бинарные аудиопотоки. Расчет кредитов производится так же, как и для HTTP-эндпоинта.

⚡ Оптимизация задержки (TTFB)

Для достижения сверхнизкой задержки (время до получения первого байта — около 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. Доступные варианты:
  • 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
Для потоковой передачи данных приложения без задержки используйте PCM. Для сохранения файлов запрашивайте MP3.
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, обращайтесь к нам по адресу api@moknah.io.