Moknah Documentação
Comece grátis
Referência da API

Fala para Texto (STT) em tempo real

Transcreva áudio ao vivo para texto em tempo real usando WebSockets

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

Transmita áudio bruto para nossos servidores e receba transcrições bidirecionais em tempo real. O servidor responde com resultados parciais (texto ao vivo conforme o usuário fala) e resultados finais (frases completas com marcações de tempo por palavra).

💳 Medidor de faturamento pré-pago (400 créditos / min)

Como as transmissões são ao vivo e imprevisíveis, usamos um medidor pré-pago. Ao conectar, reservamos imediatamente 400 créditos (pagando pelos primeiros 60 segundos). Quando você se desconecta, calculamos o uso exato por segundo e reembolsamos automaticamente os créditos não utilizados na sua conta!

Autenticação e conexão

Você deve autenticar sua conexão WebSocket. O método depende do ambiente do seu cliente:

  • Navegadores frontend: Os WebSockets padrão de navegadores não suportam cabeçalhos HTTP personalizados. Você deve incluir sua chave de API como um parâmetro de consulta (?api_key=YOUR_KEY).
  • Backend / Python / Node.js: Você pode usar o cabeçalho HTTP padrão Authorization: Bearer YOUR_API_KEY.
Parâmetro de consulta Obrigatório Tipo Descrição
api_key Condicional string Sua chave de API da Moknah. (Obrigatória aqui se não for passada pelo cabeçalho Authorization).
language Opcional string O código do idioma a ser transcrito. O padrão é ar-JO. Os códigos suportados incluem ar-SA, ar-EG, en-US, etc.

Especificações de áudio

⚠️ CRÍTICO: Apenas binário bruto

NÃO envie arquivos de áudio comprimidos (como .mp3, .m4a) ou arquivos .wav padrão com cabeçalhos pelo WebSocket. A IA gerará ruído aleatório ou strings vazias. O WebSocket aceita estritamente quadros PCM binários brutos.

Antes de enviar quadros binários pelo socket, certifique-se de que seu fluxo de áudio corresponda exatamente a:

  • Taxa de amostragem: 16.000 Hz (16 kHz)
  • Profundidade de bits: Inteiro de 16 bits (Int16)
  • Canais: 1 (Mono)
  • Tamanho do bloco: Envie em blocos pequenos (ex.: 100 ms / 3200 bytes). Blocos maiores que 256 KB serão rejeitados.

Respostas do servidor (eventos JSON)

Conforme você transmite o áudio binário para o servidor, ele responde de forma assíncrona com quadros de texto JSON.

Tipo de evento Exemplo de payload
Conexão bem-sucedida
Enviado imediatamente após a autenticação bem-sucedida.
{"status": "connected", "message": "Pronto para transmitir áudio..."}
Resultado parcial
Enviado continuamente. Usado para exibir legendas ao vivo em tempo real.
{"type": "partial", "text": "مرحبا بك في منصة"}
Resultado final
Enviado quando uma frase é concluída. Inclui carimbos de tempo.
{
  "type": "final",
  "text": "مرحبا بك في منصة مكنة.",
  "words": [
    {"word": "مرحبا", "start_time_ms": 150, "duration_ms": 300},
    {"word": "بك", "start_time_ms": 460, "duration_ms": 200}
  ]
}

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


Exemplo de integração

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

Desconexão e códigos de erro

Se a conexão for rejeitada ou cair, o WebSocket será fechado com um destes códigos específicos:

Código de fechamento Nome Descrição
1000 NORMAL_CLOSURE Transmissão encerrada com sucesso. Uso registrado e reembolsado adequadamente.
4001 MISSING_API_KEY O parâmetro ?api_key= não foi fornecido ou é inválido.
4002 UNAUTHORIZED Chave de API inválida, IP restrito ou créditos insuficientes para iniciar/continuar a transmissão.
4009 PAYLOAD_TOO_LARGE Você enviou um trecho de áudio maior que 256 KB. Transmita em buffers menores.
4290 CONCURRENT_LIMIT Muitas conexões WebSocket ativas na sua conta. O limite é de 1 transmissão ativa.
Suporte da API

Para dúvidas ou problemas relacionados à API, entre em contato conosco em api@moknah.io.