リアルタイム・テキスト・トゥ・スピーチ(TTS)
テキストを順次ストリーミングし、生のPCMまたはMP3オーディオバイトを即座に受け取ります。
リアルタイムのテキスト読み上げ(TTS)ストリーミングを行うための双方向WebSocket接続を確立します。テキストのチャンクを順次送信し(LLMの出力などに最適)、バイナリ形式の音声ストリームを継続的に受信します。クレジットの計算方法は、HTTPエンドポイントの場合と同様です。
超低遅延(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 です。オプションは以下の通りです。
|
| 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@moknah.io.