Moknah Dokumen
Mulai gratis
Referensi API

Teks ke Suara (TTS) Real-Time

Streaming teks secara bertahap dan terima byte audio PCM mentah atau MP3 secara instan

WSS /api/v1/tts/ws/

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.

⚡ Optimasi Latensi (TTFB)

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:
  • 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
Untuk streaming aplikasi tanpa latensi, gunakan PCM. Untuk menyimpan file, minta MP3.
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.
Dukungan API

Untuk pertanyaan atau masalah terkait API, hubungi kami di api@moknah.io.