Moknah ドキュメント
無料で始める
APIリファレンス

リアルタイム音声テキスト変換(STT)

WebSocketを使用して、ライブオーディオストリームをリアルタイムでテキストに書き起こす

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

未処理の音声データを当社のサーバーにストリーミングし、双方向かつリアルタイムの文字起こし結果を受け取ります。サーバーからは、部分的な結果(ユーザーの発話に合わせてリアルタイムで表示されるテキスト)と、最終的な結果(単語単位のタイムスタンプを含む完全な文)が返されます。

💳 プリペイド課金メーター (400 クレジット/分)

ストリーミングはリアルタイムで行われ、その長さは予測できないため、プリペイド方式の従量課金を採用しています。接続時に 400 クレジット(最初の60秒分)が即座に確保されますが、接続を終了すると、秒単位で正確な利用時間を計算し、未使用分のクレジットはお客様のアカウントに自動的に返還されます。

認証と接続

WebSocket接続を認証する必要があります。その方法は、クライアント環境によって異なります。

  • フロントエンドブラウザ: 標準的なブラウザのWebSocketは、カスタムHTTPヘッダーをサポートしていません。APIキーをクエリパラメータ(?api_key=YOUR_KEY)として含める必要があります。
  • バックエンド / Python / Node.js: 標準のHTTPヘッダー「Authorization: Bearer YOUR_API_KEY」を使用できます。
クエリパラメータ 必須 タイプ 説明
api_key 条件付き 文字列 Moknah APIキー。(Authorizationヘッダーで渡さない場合は、ここで指定する必要があります。)
language 任意 文字列 文字起こしを行う言語コード。デフォルトは ar-JO です。サポートされているコードには、ar-SA、ar-EG、en-US などがあります。

オーディオ仕様

⚠️ 重要:Rawバイナリのみ

WebSocket経由で、圧縮された音声ファイル(.mp3や.m4aなど)や、ヘッダーを含む標準的な.wavファイルを送信しないでください。そのようなファイルを送信すると、AIはランダムなノイズや空の文字列を出力してしまいます。WebSocketが受け付けるのは、RawバイナリPCMフレームのみです。

ソケット経由でバイナリフレームを送信する前に、オーディオストリームが以下と完全に一致していることを確認してください。

  • サンプリングレート: 16,000 Hz (16 kHz)
  • ビット深度: 16ビット整数 (Int16)
  • チャンネル: 1 (モノラル)
  • チャンクサイズ: 小さなチャンク(例:100ms / 3200バイト)に分けて送信してください。256KBを超えるチャンクは拒否されます。

サーバーレスポンス (JSONイベント)

バイナリオーディオをサーバーにストリーミングすると、サーバーはJSONテキストフレームで非同期に応答します。

イベントの種類 ペイロードの例
接続成功
認証の成功後、直ちに送信されます。
{"status": "connected", "message": "音声のストリーミングを開始する準備ができました..."}
部分的な結果
継続的に送信されます。リアルタイムでタイピングされる字幕を表示するために使用されます。
{"type": "partial", "text": "プラットフォームへようこそ"}
最終結果
文が完了した際に送信されます。タイムスタンプが含まれます。
{
  "type": "final",
  "text": "Makanaプラットフォームへようこそ。",
  "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 256KBを超えるオーディオチャンクが送信されました。より小さなバッファでストリーミングしてください。
4290 CONCURRENT_LIMIT アカウントの有効なWebSocket接続数が多すぎます。上限は1つのアクティブなストリームです。
APIサポート

APIに関するご質問や問題については、こちらまでお問い合わせください。 api@moknah.io.