Moknah Dokumentacja
Zacznij za darmo
Dokumentacja API

Zamiana mowy na tekst (STT) w czasie rzeczywistym

Transkrybuj strumieniowane na żywo audio na tekst w czasie rzeczywistym za pomocą WebSockets

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

Przesyłaj strumieniowo surowe audio do naszych serwerów i otrzymuj dwukierunkowe transkrypcje w czasie rzeczywistym. Serwer odpowiada wynikami częściowymi (tekst na żywo w trakcie mówienia) oraz wynikami końcowymi (pełne zdania ze znacznikami czasu dla poszczególnych słów).

💳 Licznik rozliczeń przedpłaconych (400 kredytów / min)

Ponieważ strumienie są transmitowane na żywo i nieprzewidywalne, stosujemy licznik przedpłacony. Po nawiązaniu połączenia natychmiast rezerwujemy 400 kredytów (opłata za pierwsze 60 sekund). Po rozłączeniu obliczamy dokładne zużycie co do sekundy i automatycznie zwracamy niewykorzystane kredyty na Twoje konto!

Uwierzytelnianie i połączenie

Musisz uwierzytelnić połączenie WebSocket. Metoda zależy od środowiska klienta:

  • Przeglądarki (frontend): Standardowe połączenia WebSocket w przeglądarkach nie obsługują niestandardowych nagłówków HTTP. Musisz przekazać klucz API jako parametr zapytania (?api_key=YOUR_KEY).
  • Backend / Python / Node.js: Możesz użyć standardowego nagłówka HTTP Authorization: Bearer YOUR_API_KEY.
Parametr zapytania Wymagane Typ Opis
api_key Warunkowy string Twój klucz API Moknah. (Wymagany tutaj, jeśli nie został przekazany w nagłówku Authorization).
language Opcjonalny string Kod języka do transkrypcji. Domyślnie ar-JO. Obsługiwane kody to m.in. ar-SA, ar-EG, en-US itp.

Specyfikacja audio

⚠️ WAŻNE: Tylko surowe dane binarne

NIE wysyłaj skompresowanych plików audio (takich jak .mp3, .m4a) ani standardowych plików .wav z nagłówkami przez WebSocket. AI wygeneruje losowy szum lub puste ciągi znaków. WebSocket akceptuje wyłącznie surowe binarne ramki PCM.

Przed wysłaniem ramek binarnych przez gniazdo upewnij się, że strumień audio dokładnie odpowiada poniższym parametrom:

  • Częstotliwość próbkowania: 16 000 Hz (16 kHz)
  • Głębia bitowa: 16-bitowa liczba całkowita (Int16)
  • Kanały: 1 (Mono)
  • Rozmiar fragmentu: Wysyłaj w małych fragmentach (np. 100 ms / 3200 bajtów). Fragmenty większe niż 256 KB zostaną odrzucone.

Odpowiedzi serwera (zdarzenia JSON)

Podczas przesyłania binarnego strumienia audio do serwera, serwer będzie odpowiadać asynchronicznie ramkami tekstowymi JSON.

Typ zdarzenia Przykładowy ładunek (payload)
Połączenie udane
Wysyłane natychmiast po pomyślnym uwierzytelnieniu.
{"status": "connected", "message": "Gotowość do przesyłania strumienia audio..."}
Wynik częściowy
Wysyłane w sposób ciągły. Służy do wyświetlania napisów na żywo w trakcie mówienia.
{"type": "partial", "text": "مرحبا بك في منصة"}
Wynik końcowy
Wysyłane po zakończeniu zdania. Zawiera znaczniki czasu.
{
  "type": "final",
  "text": "مرحبا بك في منصة مكنة.",
  "words": [
    {"word": "مرحبا", "start_time_ms": 150, "duration_ms": 300},
    {"word": "بك", "start_time_ms": 460, "duration_ms": 200}
  ]
}

Kończenie strumienia: When the user stops speaking, send a JSON text frame: {"command": "stop"} to safely close the connection and calculate the final refund.


Przykładowa integracja

# 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" }));
}

Rozłączenie i kody błędów

Jeśli połączenie zostanie odrzucone lub przerwane, WebSocket zamknie się z jednym z poniższych kodów:

Kod zamknięcia Nazwa Opis
1000 NORMAL_CLOSURE Strumień zakończony pomyślnie. Użycie zostało zarejestrowane i odpowiednio zwrócone.
4001 MISSING_API_KEY Parametr ?api_key= nie został podany lub jest nieprawidłowy.
4002 UNAUTHORIZED Nieprawidłowy klucz API, ograniczony adres IP lub niewystarczająca liczba kredytów, aby rozpocząć/kontynuować strumień.
4009 PAYLOAD_TOO_LARGE Wysłano fragment audio większy niż 256 KB. Przesyłaj strumieniowo w mniejszych buforach.
4290 CONCURRENT_LIMIT Zbyt wiele aktywnych połączeń WebSocket dla Twojego konta. Limit wynosi 1 aktywny strumień.
Wsparcie API

W razie pytań lub problemów związanych z API skontaktuj się z nami pod adresem api@moknah.io.