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

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

Преобразуйте потоковый аудиосигнал в текст в реальном времени с помощью WebSockets.

WSS wss://moknah.io/api/v1/stt/ws/

Передавайте потоковый необработанный аудиосигнал на наши серверы и получайте результаты транскрибации в реальном времени. Сервер возвращает как промежуточные результаты (текст, отображаемый по мере речи пользователя), так и итоговые (полные предложения с временными метками для каждого слова).

💳 Счетчик предоплаты (400 кредитов/мин)

Поскольку потоковые трансляции проходят в реальном времени и их ход непредсказуем, мы используем систему предоплаты. При подключении мы сразу резервируем 400 кредитов (оплата за первые 60 секунд). Когда вы завершаете сеанс, мы рассчитываем точное время использования (с точностью до секунды) и автоматически возвращаем неиспользованные кредиты на ваш счет!

Аутентификация и подключение

Вам необходимо аутентифицировать WebSocket-соединение. Метод зависит от среды клиента:

  • Браузеры для фронтенда: Стандартные браузерные WebSockets не поддерживают пользовательские HTTP-заголовки. Вам необходимо передавать API-ключ в качестве параметра запроса (?api_key=YOUR_KEY).
  • Бэкенд / Python / Node.js: Вы можете использовать стандартный HTTP-заголовок Authorization: Bearer YOUR_API_KEY.
Параметр запроса Обязательно Тип Описание
api_key Условное наклонение строка Ваш API-ключ Moknah. (Обязателен здесь, если не передан в заголовке Authorization).
language Необязательно строка Код языка для транскрибирования. По умолчанию используется ar-JO. Поддерживаемые коды: ar-SA, ar-EG, en-US и т. д.

Характеристики аудио

⚠️ КРИТИЧЕСКИ ВАЖНО: Только необработанные двоичные данные

Не отправляйте через WebSocket сжатые аудиофайлы (например, .mp3, .m4a) или стандартные файлы .wav с заголовками. В противном случае ИИ будет выдавать случайный шум или пустые строки. WebSocket принимает исключительно необработанные (raw) бинарные PCM-фреймы.

Перед отправкой бинарных кадров через сокет убедитесь, что ваш аудиопоток точно соответствует:

  • Частота дискретизации: 16 000 Гц (16 кГц)
  • Глубина цвета: 16-битное целое число (Int16)
  • Каналы: 1 (Моно)
  • Размер фрагмента: Отправляйте данные небольшими фрагментами (например, 100 мс / 3200 байт). Фрагменты размером более 256 КБ будут отклонены.

Ответы сервера (JSON-события)

По мере передачи потока бинарных аудиоданных на сервер, сервер будет асинхронно отвечать текстовыми кадрами в формате JSON.

Тип события Пример полезной нагрузки
Подключение успешно
Отправляется сразу после успешной аутентификации.
{"status": "connected", "message": "Готов к потоковой передаче аудио..."}
Частичный результат
Передается непрерывно. Используется для отображения субтитров, появляющихся по мере ввода текста в реальном времени.
{"type": "partial", "text": "Добро пожаловать на платформу"}
Окончательный результат
Отправляется при завершении предложения. Содержит временные метки.
{
  "type": "final",
  "text": "Добро пожаловать на платформу «Макна».",
  "words": [
    {"word": "مرحبا", "start_time_ms": 150, "duration_ms": 300},
    {"word": "بك", "start_time_ms": 460, "duration_ms": 200}
  ]
}

Завершение трансляции: When the user stops speaking, send a JSON text frame: {"command": "stop"} to safely close the connection and calculate the final refund.


Пример интеграции

# pip install websockets pyaudio
import asyncio
import websockets
import json
import pyaudio
import sys

API_KEY = "YOUR_API_KEY"
URL = "wss://moknah.io/api/v1/stt/ws/?language=ar-SA"

# 16kHz, 16-bit, Mono (100ms chunks)
CHUNK = 1600

async def stream_live_microphone(ws):
    audio = pyaudio.PyAudio()
    stream = audio.open(format=pyaudio.paInt16, channels=1, rate=16000, input=True, frames_per_buffer=CHUNK)

    print("🎤 Microphone is LIVE. Start speaking!")
    loop = asyncio.get_running_loop()

    try:
        while True:
            data = await loop.run_in_executor(None, stream.read, CHUNK, False)
            await ws.send(data)
            await asyncio.sleep(0.001)
    except asyncio.CancelledError:
        await ws.send(json.dumps({"command": "stop"}))
    finally:
        stream.stop_stream()
        stream.close()
        audio.terminate()

async def receive_transcriptions(ws):
    async for message in ws:
        data = json.loads(message)
        if data.get('type') == 'partial':
            sys.stdout.write(f"\r⏳ {data['text']}")
            sys.stdout.flush()
        elif data.get('type') == 'final':
            sys.stdout.write(f"\r✅ {data['text']}\n")
            sys.stdout.flush()

async def main():
    headers = {"Authorization": f"Bearer {API_KEY}"}
    async with websockets.connect(URL, additional_headers=headers) as ws:
        await asyncio.gather(
            asyncio.create_task(stream_live_microphone(ws)),
            asyncio.create_task(receive_transcriptions(ws))
        )

asyncio.run(main())
// 1. Connect to WebSocket
const ws = new WebSocket('wss://moknah.io/api/v1/stt/ws/?api_key=YOUR_API_KEY&language=ar-SA');

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.type === 'partial') {
        console.log("Live:", data.text);
    } else if (data.type === 'final') {
        console.log("Final:", data.text);
    }
};

// 2. Capture Microphone Audio on Connection
ws.onopen = async () => {
    const stream = await navigator.mediaDevices.getUserMedia({ audio: true });

    // Force 16kHz sample rate for the AudioContext
    const audioCtx = new AudioContext({ sampleRate: 16000 });
    const source = audioCtx.createMediaStreamSource(stream);
    const processor = audioCtx.createScriptProcessor(4096, 1, 1);

    processor.onaudioprocess = (e) => {
        if (ws.readyState === WebSocket.OPEN) {
            const float32Data = e.inputBuffer.getChannelData(0);

            // Convert Browser Float32 to Int16 PCM (Required by Server)
            const pcm16 = new Int16Array(float32Data.length);
            for (let i = 0; i < float32Data.length; i++) {
                pcm16[i] = Math.max(-1, Math.min(1, float32Data[i])) * 0x7FFF;
            }

            // Send binary PCM audio chunk to server
            ws.send(pcm16.buffer);
        }
    };

    source.connect(processor);
    processor.connect(audioCtx.destination);
};

// 3. Handle graceful shutdown
function stopRecording() {
    ws.send(JSON.stringify({ command: "stop" }));
}

Разрыв соединения и коды ошибок

Если соединение будет отклонено или разорвано, WebSocket закроется с одним из этих конкретных кодов:

Закрыть код Имя Описание
1000 NORMAL_CLOSURE Поток успешно завершен. Данные об использовании зафиксированы, средства возвращены в надлежащем порядке.
4001 MISSING_API_KEY Параметр ?api_key= не был передан или является недопустимым.
4002 UNAUTHORIZED Неверный API-ключ, ограниченный IP-адрес или недостаточно кредитов для запуска/продолжения потока.
4009 PAYLOAD_TOO_LARGE Вы отправили фрагмент аудио размером более 256 КБ. Передавайте данные в буферах меньшего размера.
4290 CONCURRENT_LIMIT Для вашей учетной записи открыто слишком много активных WebSocket-соединений. Лимит — 1 активный поток.
Поддержка API

По вопросам или проблемам, связанным с API, обращайтесь к нам по адресу api@moknah.io.