Moknah Documentación
Empieza gratis
Referencia de la API

Voz a texto (STT) en tiempo real

Transcribe audio en vivo a texto en tiempo real mediante WebSockets

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

Transmite audio sin procesar a nuestros servidores y recibe transcripciones bidireccionales en tiempo real. El servidor responde con resultados parciales (texto en vivo mientras el usuario habla) y resultados finales (oraciones completas con marcas de tiempo por palabra).

💳 Medidor de facturación prepaga (400 créditos / min)

Como las transmisiones son en vivo e impredecibles, usamos un medidor prepago. Al conectarte, reservamos de inmediato 400 créditos (que cubren los primeros 60 segundos). Cuando te desconectas, calculamos tu uso exacto al segundo y reembolsamos automáticamente los créditos no utilizados a tu cuenta.

Autenticación y conexión

Debes autenticar tu conexión WebSocket. El método depende del entorno de tu cliente:

  • Navegadores frontend: Los WebSockets estándar de navegador no admiten encabezados HTTP personalizados. Debes incluir tu clave API como parámetro de consulta (?api_key=YOUR_KEY).
  • Backend / Python / Node.js: Puedes usar el encabezado HTTP estándar Authorization: Bearer YOUR_API_KEY.
Parámetro de consulta Obligatorio Tipo Descripción
api_key Condicional string Tu clave API de Moknah. (Obligatoria aquí si no se envía mediante el encabezado Authorization).
language Opcional string El código del idioma a transcribir. El valor predeterminado es ar-JO. Los códigos admitidos incluyen ar-SA, ar-EG, en-US, etc.

Especificaciones de audio

⚠️ CRÍTICO: Solo binario sin procesar

NO envíes archivos de audio comprimidos (como .mp3, .m4a) ni archivos .wav estándar con encabezados por el WebSocket. La IA generará ruido aleatorio o cadenas vacías. El WebSocket acepta estrictamente tramas PCM binarias sin procesar.

Antes de enviar tramas binarias por el socket, asegúrate de que tu flujo de audio coincida exactamente con lo siguiente:

  • Frecuencia de muestreo: 16,000 Hz (16 kHz)
  • Profundidad de bits: Entero de 16 bits (Int16)
  • Canales: 1 (Mono)
  • Tamaño de fragmento: Envía en fragmentos pequeños (p. ej., 100 ms / 3200 bytes). Los fragmentos mayores de 256 KB serán rechazados.

Respuestas del servidor (eventos JSON)

A medida que transmites audio binario al servidor, este responderá de forma asíncrona con tramas de texto JSON.

Tipo de evento Ejemplo de carga útil
Conexión exitosa
Se envía inmediatamente tras una autenticación exitosa.
{"status": "connected", "message": "Listo para transmitir audio..."}
Resultado parcial
Se envía de forma continua. Se usa para mostrar subtítulos en vivo mientras se habla.
{"type": "partial", "text": "مرحبا بك في منصة"}
Resultado final
Se envía cuando se completa una oración. Incluye marcas de tiempo.
{
  "type": "final",
  "text": "مرحبا بك في منصة مكنة.",
  "words": [
    {"word": "مرحبا", "start_time_ms": 150, "duration_ms": 300},
    {"word": "بك", "start_time_ms": 460, "duration_ms": 200}
  ]
}

Finalizar la transmisión: When the user stops speaking, send a JSON text frame: {"command": "stop"} to safely close the connection and calculate the final refund.


Ejemplo de integración

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

Desconexión y códigos de error

Si la conexión es rechazada o se interrumpe, el WebSocket se cerrará con uno de estos códigos específicos:

Código de cierre Nombre Descripción
1000 NORMAL_CLOSURE La transmisión finalizó correctamente. El uso se registró y se reembolsó según corresponde.
4001 MISSING_API_KEY El parámetro ?api_key= no se proporcionó o no es válido.
4002 UNAUTHORIZED Clave de API no válida, IP restringida o créditos insuficientes para iniciar o continuar la transmisión.
4009 PAYLOAD_TOO_LARGE Enviaste un fragmento de audio mayor a 256 KB. Transmite en búferes más pequeños.
4290 CONCURRENT_LIMIT Demasiadas conexiones WebSocket activas para tu cuenta. El límite es de 1 transmisión activa.
Soporte de API

Para preguntas o problemas relacionados con la API, contáctanos en api@moknah.io.