Moknah دستاویزات
مفت شروع کریں
API ریفرنس

ریئل ٹائم ٹیکسٹ ٹو اسپیچ (TTS)

متن کو بتدریج اسٹریم کریں اور فوری طور پر خام PCM یا MP3 آڈیو بائٹس حاصل کریں

WSS /api/v1/tts/ws/

ریئل ٹائم ٹیکسٹ ٹو اسپیچ اسٹریمنگ کے لیے دو طرفہ WebSocket کنکشن قائم کرتا ہے۔ متن کے حصے بتدریج بھیجیں (LLM آؤٹ پٹ کے لیے بہترین) اور مسلسل بائنری آڈیو اسٹریمز حاصل کریں۔ کریڈٹس کا حساب HTTP اینڈ پوائنٹ کی طرح ہی لگایا جاتا ہے۔

⚡ تاخیر میں بہتری (TTFB)

انتہائی کم تاخیر (~200ms ٹائم ٹو فرسٹ بائٹ) حاصل کرنے کے لیے، یقینی بنائیں کہ آپ کے متن کے حصے واضح رموزِ اوقاف (ختمہ .، فجائیہ نشان !، یا سوالیہ نشان ؟) پر ختم ہوں۔ مصنوعی ذہانت بہترین انسانی لب و لہجہ یقینی بنانے کے لیے جملے کی حد شناخت ہونے تک متن کو قدرتی طور پر بفر کرتی ہے۔

تصدیق

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 لازمی اسٹرنگ (string) ابتدائی پیغام کے لیے لازمی طور پر "init" ہونا چاہیے۔
voice_id لازمی عددی (integer) وائس ID از آوازوں کی فہرست.
output_format اختیاری اسٹرنگ (string) مطلوبہ آڈیو فارمیٹ۔ ڈیفالٹ 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 اختیاری عددی (integer) 1 (نارمل، ڈیفالٹ)، 2 (AI بہتری / عربی تشکیل) یا 3 (AI شاعر)۔ کریڈٹ کی لاگت پر اثر انداز ہوتا ہے۔ 2 اور 3 صرف عربی مواد کے لیے دستیاب ہیں؛ language دیکھیں۔
language اختیاری اسٹرنگ (string) مواد کی زبان بطور ISO 639-1 کوڈ، مثال کے طور پر ar یا en (علاقائی کوڈز جیسے ar-JO قابل قبول ہیں)۔ یہ طے کرتا ہے کہ کون سے پری ریکارڈنگ موڈز کی اجازت ہے اور اسے آواز کو نہیں بھیجا جاتا۔ موڈز 2 اور 3 صرف عربی (ar) کے لیے دستیاب ہیں۔ اگر language چھوڑ دیا جائے تو 2 اور 3 کا مطلب عربی ہی لیا جاتا ہے، تاکہ موجودہ انٹیگریشنز کام کرتی رہیں۔ 2 یا 3 کے ساتھ کوئی دوسری زبان، یا کوئی نامعلوم کوڈ دینے پر ایرر پیغام ملتا ہے اور اسٹریم شروع نہیں ہوتی۔
voice_settings اختیاری آبجیکٹ (object) آواز کی تخصیص کے اختیارات۔ نیچے آواز کی ترتیبات کا سیکشن دیکھیں۔

آواز کی ترتیبات کا آبجیکٹ

اسٹریمنگ دونوں انجنوں کے ساتھ اپنے فی حرف ریٹ پر کام کرتی ہے، جسے موڈ سے ضرب دیا جاتا ہے: emotion (ڈیفالٹ) اور fast_mode ×1، quality اور studio ×2۔ ایڈوانسڈ انجن کی آوازوں کی لاگت ×1.5 ہے۔

  • اسٹینڈرڈ انجن کی آوازیں ہر موڈ میں اسٹریم ہوتی ہیں: emotion (ڈیفالٹ، سب سے کم تاخیر)، quality، اور studio۔ fast_mode کم تاخیر والے ماڈل پر منتقل کر دیتا ہے۔
  • ایڈوانسڈ انجن کی آوازیں جملہ بہ جملہ اسٹریم ہوتی ہیں: ہر جملے کی آڈیو اس کے مکمل ہوتے ہی شروع ہو جاتی ہے۔ pcm_* یا mp3_* آؤٹ پٹ فارمیٹس استعمال کریں (ان آوازوں کے لیے Opus دستیاب نہیں ہے)۔

معیاری انجن کی آوازیں

پیرامیٹر قسم رینج ڈیفالٹ تفصیل
mode اسٹرنگ (string) emotion, quality, studio emotion اختیاری۔ emotion (جذبات اور لہجہ، ×1)، quality (معیاری جذبات اور لہجہ، ×2) یا studio (اسٹوڈیو کوالٹی، ×2)۔ emotion اور quality میں صرف temperature اور similarity لاگو ہوتے ہیں۔
temperature عددی (integer) 0 – 100 25 کم = مستحکم اور قابلِ پیش گوئی، زیادہ = تخلیقی اور متنوع۔
similarity عددی (integer) 0 – 100 100 آواز اصل وائس کلون سے کس حد تک مشابہت رکھتی ہے۔
speed اعشاری عدد (float) 0.5 – 2.0 1.0 پلے بیک اسپیڈ ملٹی پلائر۔
fast_mode عددی (integer) 0, 1, or 2 0 1 یا 2 کم لیٹنسی ماڈل (×1 کریڈٹس) پر منتقل کرتا ہے اور mode کو اوور رائیڈ کرتا ہے۔ 0 = بند۔

ایڈوانسڈ انجن کی آوازیں

پیرامیٹر قسم قدریں تفصیل
context اسٹرنگ (string) 500 حروف تک سب سے مضبوط کنٹرول۔ لہجہ، احساس، موڈ یا مقصد بیان کریں۔
setting اسٹرنگ (string) 500 حروف تک منظر اور موڈ۔
style اسٹرنگ (string) neutral, warm, energetic, serious, cheerful, poetic ادائیگی کا مجموعی انداز۔
pace اسٹرنگ (string) slow, normal, fast بولنے کی رفتار۔

مشورہ: تیز ترین پہلی آڈیو حاصل کرنے کے لیے مکمل جملے (جو . ! ? یا نئی لائن پر ختم ہوں) بھیجیں۔

اسٹریمنگ پائپ لائن

1. متن کے ٹکڑے بھیجیں

جیسے جیسے آپ کا LLM متن تیار کرے، اسے بتدریج بھیجیں:

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

سرور فوری طور پر اس ٹکڑے کو پروسیس کرے گا، اس لمبائی کے مخصوص کریڈٹس کاٹے گا، اور واپس آڈیو اسٹریم کرنا شروع کر دے گا۔

2. تکمیل کا اشارہ دیں (روکیں)

جب آپ کے متن کی تیاری مکمل ہو جائے تو روکنے کا سگنل بھیجیں:

{"type": "stop"}

سرور اپنے بفر میں موجود بقیہ متن کی سنتھیسز مکمل کرے گا، آڈیو کے آخری بائٹس آپ کو بھیجے گا، اور اسٹریمنگ کے اختتام کا سگنل بھیج دے گا۔

پیغامات کی وصولی

سرور WebSocket کے ذریعے دو طرح کے فریم بھیجتا ہے:

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://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"}

بندش کے کوڈز اور خرابیاں

WebSocket کنکشن ان معیاری کوڈز میں سے کسی ایک کے ساتھ بند ہو سکتا ہے:

کوڈ قسم تفصیل
1000 SUCCESS اسٹریم قدرتی طور پر مکمل ہو گئی۔
3011 GENERATION_ERROR اپ سٹریم API پر آڈیو جنریشن ناکام ہو گئی۔ درخواست دوبارہ کوشش کریں۔
4001 MISSING_API_KEY Authorization ہیڈر میں کوئی API کلید فراہم نہیں کی گئی۔
4002 AUTH_FAILED غلط کلید، غیر فعال اکاؤنٹ، ناکافی ابتدائی کریڈٹس، یا IP پابندی۔
4290 CONCURRENT_LIMIT صارف کے پاس پہلے سے ہی ایک فعال TTS WebSocket کنکشن موجود ہے۔ فی صارف حد 1 ہے۔
API سپورٹ

API سے متعلق سوالات یا مسائل کے لیے، ہم سے یہاں رابطہ کریں api@moknah.io.