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

リアルタイム・テキスト・トゥ・スピーチ(TTS)

テキストを順次ストリーミングし、生のPCMまたはMP3オーディオバイトを即座に受け取ります。

WSS /api/v1/tts/ws/

リアルタイムのテキスト読み上げ(TTS)ストリーミングを行うための双方向WebSocket接続を確立します。テキストのチャンクを順次送信し(LLMの出力などに最適)、バイナリ形式の音声ストリームを継続的に受信します。クレジットの計算方法は、HTTPエンドポイントの場合と同様です。

⚡ レイテンシの最適化 (TTFB)

超低遅延(Time-To-First-Byte:約200ms)を実現するには、テキストの各チャンクを「ハードな」句読点(ピリオド「.」、感嘆符「!」、または疑問符「?」)で終わらせるようにしてください。AIは、人間のような完璧な抑揚を再現するため、文の区切りを検出するまで自然にテキストをバッファリングします。

認証

WebSocketのハンドシェイク中に、Authorizationヘッダーを使用して認証を行います。

Authorization: Bearer YOUR_API_KEY

接続設定

接続後、希望する設定を含む初期化メッセージを送信してください。

{
  "type": "init",
  "voice_id": 1710,
  "prerecording": 1,
  "language": "ar",
  "output_format": "pcm_24000",
  "voice_settings": {
    "temperature": 25,
    "similarity": 100,
    "expressiveness": 0,
    "speed": 1.0,
    "fast_mode": 2
  }
}

初期化パラメータ

パラメータ 必須 タイプ 説明
type 必須 文字列 初期化メッセージでは "init" である必要があります。
voice_id 必須 整数 ~からの音声ID ボイスリスト.
output_format 任意 文字列 希望するオーディオ形式。デフォルトは pcm_24000 です。オプションは以下の通りです。
  • MP3: mp3_22050_32, mp3_44100_32, mp3_44100_64, mp3_44100_96, mp3_44100_128, mp3_44100_192
  • PCM: pcm_8000, pcm_16000, pcm_22050, pcm_24000, pcm_44100
遅延のないアプリのストリーミングにはPCMを使用し、ファイルの保存にはMP3を指定してください。
prerecording 任意 整数 1(通常・デフォルト)、2(AIによる強化/アラビア語のタシュキール)、または3(AI詩人)。クレジットの消費量に影響します。2と3はアラビア語のコンテンツでのみ利用可能です(言語設定を参照)。
language 任意 文字列 ISO 639-1コード(例:arやen)で指定するコンテンツ言語です(ar-JOのような地域コードも使用可能です)。この設定は利用可能な事前録音モードを決定するものであり、音声には送信されません。 モード2と3は、アラビア語(ar)でのみ利用可能です。言語が指定されていない場合、モード2と3はアラビア語として扱われるため、既存の統合機能はそのまま動作します。アラビア語以外の言語でモード2または3を指定した場合、あるいは不明なコードを指定した場合は、エラーメッセージが返され、ストリームは初期化されません。
voice_settings 任意 物体 音声のカスタマイズオプション。以下の「音声設定」セクションをご覧ください。

音声設定オブジェクト

ストリーミングは両エンジンで利用可能で、文字あたりの基本料金にモードに応じた倍率が適用されます(emotion(デフォルト)およびfast_modeは1倍、qualityおよびstudioは2倍)。Advancedエンジンの音声は1.5倍の料金となります。

  • 標準エンジンの音声は、emotion(デフォルト、最小レイテンシ)、quality、studioのすべてのモードでストリーミングされます。fast_modeでは、低レイテンシモデルに切り替わります。
  • 高度なエンジン音声は文単位でストリーミングされます。つまり、各文の音声は、その文の生成が完了次第、再生が開始されます。出力形式には pcm_* または mp3_* を使用してください(これらの音声では Opus は利用できません)。

標準のエンジン音

パラメータ タイプ 範囲 デフォルト 説明
mode 文字列 emotion, quality, studio emotion 任意。emotion(感情と方言、×1)、quality(品質・感情・方言、×2)、または studio(スタジオ品質、×2)から選択します。emotion および quality の場合、適用されるのは temperature(温度)と similarity(類似度)のみです。
temperature 整数 0 – 100 25 低い=安定的で予測可能、高い=創造的で変化に富む。
similarity 整数 0 – 100 100 音声が元のボイスクローンとどの程度忠実に一致しているか。
speed 浮かぶ 0.5 – 2.0 1.0 再生速度の倍率
fast_mode 整数 0, 1, or 2 0 1または2に設定すると、低遅延モデル(クレジット×1)に切り替わり、モード設定が上書きされます。0 = オフ。

高度なエンジンサウンド

パラメータ タイプ 価値観 説明
context 文字列 最大500文字 最も強力な制御要素。アクセント、感覚、ムード、あるいは目的を記述してください。
setting 文字列 最大500文字 場面と雰囲気。
style 文字列 neutral, warm, energetic, serious, cheerful, poetic 全体的な伝え方のスタイル
pace 文字列 slow, normal, fast 話すペース

ヒント:最初の音声を最速で生成するには、完全な文(「.」「!」「?」または改行で終わるもの)を送信してください。

ストリーミングパイプライン

1. テキストチャンクを送信する

LLMがテキストを生成するのに合わせて、順次送信してください。

{"type": "text", "data": "مرحبا بكم."}

サーバーは即座にそのチャンクを処理し、その長さに応じたクレジットを差し引いた上で、音声のストリーミングを開始します。

2. 完了の合図(停止)

テキスト生成が完全に完了したら、停止信号を送信してください:

{"type": "stop"}

サーバーは、バッファに残っているテキストの合成を完了し、最終的な音声データを送信(フラッシュ)した後、ストリーム終了(End of Stream)信号を送信します。

メッセージの受信

サーバーは、WebSocket経由で2種類のフレームをプッシュします。

1. バイナリオーディオチャンク (PCM / MP3)

生成された順にストリーミングされる、生のオーディオバイトデータです。形式は指定した `output_format` に依存します(デフォルトは 24kHz / 16-bit PCM)。MP3 を指定した場合は、これらのバイトデータを直接ファイルに書き込むことができます。

2. JSON制御メッセージ

初期化完了:

{"status": "ready", "message": "初期化が完了し、テキストを受信する準備が整いました。"}

ストリームの終了(安全なクローズ信号):

{"type": "end_of_stream"}

このメッセージを受信した時点で、音声チャンクの 100% が配信済みであることが保証されます。クライアント側で WebSocket 接続を安全に閉じられます。

ストリーム途中でのエラー:

{"error": "配信中のクレジット不足"}

本番環境対応の例

# pip install websockets
import asyncio
import websockets
import json

API_KEY = "YOUR_API_KEY"
url = "wss://moknah.io/api/v1/tts/ws/"

async def stream_tts():
    headers = {"Authorization": f"Bearer {API_KEY}"}
    async with websockets.connect(url, additional_headers=headers) as ws:
        # 1. Initialize session (Requesting MP3 so we can save to file)
        await ws.send(json.dumps({
            "type": "init",
            "voice_id": 1710,
            "output_format": "mp3_44100_128",
            "voice_settings": {"fast_mode": 2}
        }))
        print(f"Server: {await ws.recv()}")

        # 2. Receiver Task
        async def receive_audio():
            with open("audio.mp3", "wb") as f:
                async for msg in ws:
                    if isinstance(msg, bytes):
                        f.write(msg)
                    else:
                        data = json.loads(msg)
                        if data.get("type") == "end_of_stream":
                            print("✅ Stream finished safely.")
                            await ws.close()
                            break

        receiver = asyncio.create_task(receive_audio())

        # 3. Send Text
        for chunk in ["مرحبا بكم.", "في منصة مُكنة."]:
            await ws.send(json.dumps({"type": "text", "data": chunk}))
            await asyncio.sleep(0.5)

        # 4. Signal Stop
        await ws.send(json.dumps({"type": "stop"}))
        await receiver

asyncio.run(stream_tts())
// npm install ws
const WebSocket = require('ws');
const fs = require('fs');

const API_KEY = "YOUR_API_KEY";
const ws = new WebSocket('wss://moknah.io/api/v1/tts/ws/', {
    headers: { "Authorization": `Bearer ${API_KEY}` }
});

const audioStream = fs.createWriteStream('audio.mp3');

ws.on('open', function open() {
    // Requesting MP3 to safely write to an MP3 file
    ws.send(JSON.stringify({
        type: "init",
        voice_id: 1710,
        output_format: "mp3_44100_128",
        voice_settings: { fast_mode: 2 }
    }));
});

ws.on('message', function incoming(data, isBinary) {
    if (isBinary) {
        audioStream.write(data); // Save MP3 chunks
    } else {
        const msg = JSON.parse(data.toString());
        if (msg.status === 'ready') {
            console.log("Ready! Sending text...");
            ws.send(JSON.stringify({ type: "text", data: "مرحبا بكم." }));
            setTimeout(() => ws.send(JSON.stringify({ type: "text", data: "في منصة مُكة." })), 500);
            setTimeout(() => ws.send(JSON.stringify({ type: "stop" })), 1000);
        } else if (msg.type === 'end_of_stream') {
            console.log("✅ All audio received. Closing connection.");
            ws.close();
        }
    }
});
<?php
// composer require textalk/websocket
require 'vendor/autoload.php';
use WebSocket\Client;

$apiKey = "YOUR_API_KEY";
$client = new Client("wss://moknah.io/api/v1/tts/ws/", [
    'headers' => ['Authorization' => "Bearer $apiKey"],
    'timeout' => 60
]);

// 1. Initialize (Requesting MP3 format)
$client->text(json_encode([
    "type" => "init",
    "voice_id" => 1710,
    "output_format" => "mp3_44100_128",
    "voice_settings" => ["fast_mode" => 2]
]));
echo "Server: " . $client->receive() . "\n";

// 2. Send Text Chunks
$client->text(json_encode(["type" => "text", "data" => "مرحبا بكم."]));
$client->text(json_encode(["type" => "text", "data" => "في منصة مُكنة."]));
$client->text(json_encode(["type" => "stop"]));

// 3. Receive Audio & Control Messages
$audioFile = fopen("audio.mp3", "wb");
while (true) {
    $message = $client->receive();
    $decoded = json_decode($message, true);

    if ($decoded && isset($decoded['type']) && $decoded['type'] == 'end_of_stream') {
        echo "✅ Stream finished successfully.\n";
        break;
    } elseif (!$decoded) {
        // If it can't be decoded as JSON, it's our binary MP3 audio chunk
        fwrite($audioFile, $message);
    }
}
fclose($audioFile);
$client->close();
?>
# Standard cURL does not support bidirectional WebSockets easily.
# Use 'websocat' to test WebSockets from the command line:

websocat wss://moknah.io/api/v1/tts/ws/ \
  -H "Authorization: Bearer YOUR_API_KEY"

# Once connected, paste the JSON payloads interactively:
{"type": "init", "voice_id": 1710, "output_format": "mp3_44100_128"}

{"type": "text", "data": "مرحبا بكم."}

{"type": "stop"}

クローズコードとエラー

WebSocket接続は、以下の標準コードのいずれかで終了する場合があります。

コード タイプ 説明
1000 成功 ストリームが正常に完了しました。
3011 生成エラー アップストリームAPIでの音声生成に失敗しました。リクエストを再試行してください。
4001 APIキーが指定されていません AuthorizationヘッダーにAPIキーが指定されていません。
4002 認証失敗 無効なキー、無効なアカウント、初期クレジットの不足、またはIP制限。
4290 同時実行制限 ユーザーはすでにアクティブなTTS WebSocket接続を確立しています。ユーザーあたりの上限は1つです。
APIサポート

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