Teks ke Suara (TTS) Real-Time
Streaming teks secara bertahap dan terima byte audio PCM mentah atau MP3 secara instan
Membuat koneksi WebSocket dua arah untuk streaming teks ke suara secara real-time. Kirim potongan teks secara bertahap (ideal untuk output LLM) dan terima aliran audio biner secara berkelanjutan. Kredit dihitung sama persis seperti endpoint HTTP.
Untuk mencapai latensi sangat rendah (~200ms Time-To-First-Byte), pastikan potongan teks Anda diakhiri dengan tanda baca akhir kalimat (titik ., tanda seru !, atau tanda tanya ?). AI secara alami menyangga teks hingga mendeteksi batas kalimat untuk memastikan intonasi manusia yang sempurna.
Autentikasi
Autentikasi menggunakan header Authorization saat handshake WebSocket:
Authorization: Bearer YOUR_API_KEY
Pengaturan Koneksi
Setelah terhubung, kirim pesan inisialisasi dengan konfigurasi yang Anda inginkan:
{
"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
}
}
Parameter Inisialisasi
| Parameter | Wajib | Jenis | Deskripsi |
|---|---|---|---|
| type | wajib | string | Harus bernilai "init" untuk pesan inisialisasi. |
| voice_id | wajib | integer | ID Suara dari daftar suara. |
| output_format | opsional | string | Format audio yang diinginkan. Default-nya adalah pcm_24000. Pilihannya meliputi:
|
| prerecording | opsional | integer | 1 (normal, default), 2 (peningkatan AI / Tashkeel Arab), atau 3 (Penyair AI). Memengaruhi biaya kredit. 2 dan 3 hanya tersedia untuk konten bahasa Arab; lihat language. |
| language | opsional | string | Bahasa konten sebagai kode ISO 639-1, misalnya ar atau en (kode wilayah seperti ar-JO diterima). Parameter ini menentukan mode prarekaman mana yang diizinkan dan tidak dikirim ke suara. Mode 2 dan 3 hanya tersedia untuk bahasa Arab (ar). Jika language dikosongkan, 2 dan 3 berarti bahasa Arab, sehingga integrasi yang ada tetap berfungsi. Bahasa lain dengan mode 2 atau 3, atau kode yang tidak dikenal, akan mengembalikan pesan kesalahan dan aliran tidak akan diinisialisasi. |
| voice_settings | opsional | object | Opsi kustomisasi suara. Lihat bagian Pengaturan Suara di bawah. |
Objek Pengaturan Suara
Streaming berfungsi dengan kedua mesin dengan tarif per karakter tersendiri, dikalikan dengan mode: emotion (default) dan fast_mode ×1, quality dan studio ×2. Suara mesin Lanjutan berbiaya ×1,5.
- Suara mesin Standar melakukan streaming di setiap mode: emotion (default, latensi terendah), quality, dan studio. fast_mode beralih ke model latensi rendah.
- Suara mesin Lanjutan melakukan streaming kalimat demi kalimat: audio untuk setiap kalimat dimulai segera setelah kalimat selesai. Gunakan format output pcm_* atau mp3_* (Opus tidak tersedia untuk suara ini).
Suara mesin Standar
| Parameter | Jenis | Rentang | Default | Deskripsi |
|---|---|---|---|---|
| mode | string | emotion, quality, studio | emotion | Opsional. emotion (Emosi & dialek, ×1), quality (Emosi & dialek berkualitas, ×2), atau studio (Kualitas Studio, ×2). Pada emotion dan quality, hanya temperature dan similarity yang berlaku. |
| temperature | integer | 0 – 100 | 25 | Lebih rendah = stabil dan terprediksi, Lebih tinggi = kreatif dan bervariasi. |
| similarity | integer | 0 – 100 | 100 | Seberapa mirip ucapan dengan klon suara aslinya. |
| speed | float | 0.5 – 2.0 | 1.0 | Pengali kecepatan pemutaran. |
| fast_mode | integer | 0, 1, or 2 | 0 | 1 atau 2 beralih ke model latensi rendah (×1 kredit) dan mengesampingkan mode. 0 = nonaktif. |
Suara mesin Lanjutan
| Parameter | Jenis | Nilai | Deskripsi |
|---|---|---|---|
| context | string | hingga 500 karakter | Kontrol paling kuat. Deskripsikan aksen, perasaan, suasana, atau tujuan. |
| setting | string | hingga 500 karakter | Suasana dan mood. |
| style | string | neutral, warm, energetic, serious, cheerful, poetic | Gaya penyampaian secara keseluruhan. |
| pace | string | slow, normal, fast | Tempo bicara. |
Tips: kirim kalimat utuh (diakhiri dengan . ! ? atau baris baru) untuk mendapatkan audio pertama tercepat.
Pipeline Streaming
1. Kirim Potongan Teks
Kirim teks secara bertahap saat LLM Anda menghasilkannya:
{"type": "text", "data": "مرحبا بكم."}
Server akan langsung memproses potongan tersebut, memotong kredit sesuai panjangnya, dan mulai mengalirkan audio kembali.
2. Beri Sinyal Selesai (Berhenti)
Saat pembuatan teks Anda benar-benar selesai, kirim sinyal berhenti:
{"type": "stop"}
Server akan menyelesaikan sintesis teks yang tersisa di buffer, mengirimkan byte audio terakhir kepada Anda, lalu mengirim sinyal Akhir Aliran (End of Stream).
Menerima Pesan
Server mengirimkan dua jenis frame melalui WebSocket:
1. Potongan Audio Biner (PCM / MP3)
Byte audio mentah yang dialirkan secepat saat dihasilkan. Formatnya bergantung pada output_format yang Anda minta (default-nya PCM 16-bit pada 24kHz). Jika Anda meminta MP3, Anda dapat menulis byte ini langsung ke file.
2. Pesan Kontrol JSON
Inisialisasi Siap:
{"status": "ready", "message": "Diinisialisasi dan siap menerima teks."}
Akhir Aliran (Sinyal Penutupan Aman):
{"type": "end_of_stream"}
Saat Anda menerima pesan ini, secara matematis dijamin bahwa 100% potongan audio telah terkirim. Anda sekarang dapat menutup koneksi WebSocket dengan aman di sisi klien.
Kesalahan di Tengah Aliran:
{"error": "Kredit tidak mencukupi selama streaming"}
Contoh Siap Produksi
# pip install websockets
import asyncio
import websockets
import json
API_KEY = "YOUR_API_KEY"
url = "wss://api.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://api.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://api.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://api.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"}
Kode Penutupan & Kesalahan
Koneksi WebSocket dapat ditutup dengan salah satu kode standar berikut:
| Kode | Jenis | Deskripsi |
|---|---|---|
1000 |
SUCCESS | Aliran selesai secara normal. |
3011 |
GENERATION_ERROR | Pembuatan audio gagal pada API hulu. Coba lagi permintaan tersebut. |
4001 |
MISSING_API_KEY | Tidak ada kunci API yang diberikan di header Authorization. |
4002 |
AUTH_FAILED | Kunci tidak valid, akun tidak aktif, kredit awal tidak mencukupi, atau pembatasan IP. |
4290 |
CONCURRENT_LIMIT | Pengguna sudah memiliki koneksi WebSocket TTS yang aktif. Batasnya adalah 1 per pengguna. |
Untuk pertanyaan atau masalah terkait API, hubungi kami di api@moknah.io.