Moknah Doku
Kostenlos starten
API-Referenz

Echtzeit-Sprache-zu-Text (STT)

Transkribieren Sie Live-Audiostreams in Echtzeit über WebSockets in Text

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

Streamen Sie Roh-Audio an unsere Server und erhalten Sie bidirektionale Echtzeit-Transkriptionen. Der Server antwortet mit Teilergebnissen (Live-Text während der Benutzer spricht) und Endergebnissen (vollständige Sätze mit Zeitstempeln auf Wortebene).

💳 Prepaid-Abrechnungszähler (400 Credits / Min.)

Da Streams live und unvorhersehbar sind, verwenden wir einen Prepaid-Zähler. Bei Verbindungsaufbau reservieren wir sofort 400 Credits (für die ersten 60 Sekunden). Wenn Sie die Verbindung trennen, berechnen wir Ihre genaue Nutzung sekundengenau und erstatten die ungenutzten Credits automatisch auf Ihr Konto zurück!

Authentifizierung & Verbindung

Sie müssen Ihre WebSocket-Verbindung authentifizieren. Die Methode hängt von Ihrer Client-Umgebung ab:

  • Frontend-Browser: Standard-Browser-WebSockets unterstützen keine benutzerdefinierten HTTP-Header. Sie müssen Ihren API-Schlüssel als Abfrageparameter übergeben (?api_key=YOUR_KEY).
  • Backend / Python / Node.js: Sie können den Standard-HTTP-Header Authorization: Bearer YOUR_API_KEY verwenden.
Abfrageparameter Erforderlich Typ Beschreibung
api_key Bedingt string Ihr Moknah-API-Schlüssel. (Hier erforderlich, falls nicht über den Authorization-Header übergeben).
language Optional string Der Sprachcode für die Transkription. Standard ist ar-JO. Unterstützte Codes sind u. a. ar-SA, ar-EG, en-US usw.

Audiospezifikationen

⚠️ WICHTIG: Nur Raw-Binärdaten

Senden Sie KEINE komprimierten Audiodateien (wie .mp3, .m4a) oder Standard-.wav-Dateien mit Headern über das WebSocket. Die KI gibt sonst zufälliges Rauschen oder leere Zeichenfolgen aus. Das WebSocket akzeptiert ausschließlich Raw-Binary-PCM-Frames.

Bevor Sie Binär-Frames über den Socket senden, stellen Sie sicher, dass Ihr Audiostream genau folgenden Vorgaben entspricht:

  • Abtastrate: 16.000 Hz (16 kHz)
  • Bittiefe: 16-Bit-Ganzzahl (Int16)
  • Kanäle: 1 (Mono)
  • Chunk-Größe: In kleinen Chunks senden (z. B. 100 ms / 3200 Byte). Chunks über 256 KB werden abgelehnt.

Serverantworten (JSON-Ereignisse)

Während Sie Binär-Audio an den Server streamen, antwortet der Server asynchron mit JSON-Text-Frames.

Ereignistyp Payload-Beispiel
Verbindung erfolgreich
Wird sofort nach erfolgreicher Authentifizierung gesendet.
{"status": "connected", "message": "Bereit zum Streamen von Audio..."}
Teilergebnis
Wird kontinuierlich gesendet. Dient zur Anzeige von Live-Untertiteln in Echtzeit.
{"type": "partial", "text": "مرحبا بك في منصة"}
Endergebnis
Wird gesendet, wenn ein Satz abgeschlossen ist. Enthält Zeitstempel.
{
  "type": "final",
  "text": "مرحبا بك في منصة مكنة.",
  "words": [
    {"word": "مرحبا", "start_time_ms": 150, "duration_ms": 300},
    {"word": "بك", "start_time_ms": 460, "duration_ms": 200}
  ]
}

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


Beispielintegration

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

Trennungs- & Fehlercodes

Wenn die Verbindung abgelehnt oder unterbrochen wird, schließt der WebSocket mit einem dieser spezifischen Codes:

Schließcode Name Beschreibung
1000 NORMAL_CLOSURE Stream erfolgreich beendet. Nutzung protokolliert und entsprechend erstattet.
4001 MISSING_API_KEY Der Parameter ?api_key= wurde nicht angegeben oder ist ungültig.
4002 UNAUTHORIZED Ungültiger API-Schlüssel, eingeschränkte IP oder unzureichende Credits zum Starten/Fortsetzen des Streams.
4009 PAYLOAD_TOO_LARGE Sie haben ein Audio-Segment gesendet, das größer als 256 KB ist. Streamen Sie in kleineren Puffern.
4290 CONCURRENT_LIMIT Zu viele aktive WebSocket-Verbindungen für Ihr Konto. Das Limit liegt bei 1 aktiven Stream.
API-Support

Bei Fragen oder Problemen rund um die API kontaktieren Sie uns unter api@moknah.io.