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

ٹیکسٹ ٹو اسپیچ (TTS)

متن کو قدرتی آواز والی گفتگو میں تبدیل کریں

POST /api/v1/tts/generate/

AI وائس سنتھیسز کا استعمال کرتے ہوئے متن کو آواز میں تبدیل کریں۔ ایک MP3 آڈیو فائل واپس کرتا ہے۔

تصدیق

Authorization ہیڈر میں اپنی API کلید شامل کریں۔

درخواست کی باڈی (Request Body)

پیرامیٹر لازمی قسم تفصیل
text لازمی اسٹرنگ (string) تبدیل کرنے کے لیے متن (زیادہ سے زیادہ 1500 حروف)
output_format اختیاری اسٹرنگ (string) مطلوبہ آڈیو آؤٹ پٹ فارمیٹ۔ codec_sampleRate_bitrate کے طور پر متعین کیا جاتا ہے (مثلاً mp3_22050_32)۔ ڈیفالٹ mp3_44100_128 ہے۔ مکمل فہرست کے لیے نیچے آؤٹ پٹ فارمیٹس کا سیکشن دیکھیں۔
voice_id لازمی عددی (integer) وائس ID از آوازوں کی فہرست.
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 کے ساتھ کوئی دوسری زبان، یا کوئی نامعلوم کوڈ، details.language کے تحت وجہ کے ساتھ 400 INVALID_REQUEST واپس کرتا ہے۔
voice_settings اختیاری اسٹرنگ (JSON) آواز کی تخصیص کے اختیارات

سپورٹ شدہ آؤٹ پٹ فارمیٹس

output_format پیرامیٹر درج ذیل اقدار میں سے کوئی بھی ہو سکتا ہے:

  • MP3: mp3_22050_32, mp3_24000_48, 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_32000, pcm_44100, pcm_48000
  • Opus: opus_48000_32, opus_48000_64, opus_48000_96, opus_48000_128, opus_48000_192
  • WAV: wav_16000, wav_22050, wav_24000, wav_44100, wav_48000 — انجن کے اپنے آؤٹ پٹ کی 16-بٹ مونو WAV (بغیر کوالٹی کم ہوئے)۔ اسٹریمنگ WebSocket پر دستیاب نہیں؛ وہاں pcm_* استعمال کریں۔

یہ سیکشن بطور حوالہ کام کرتا ہے، تاکہ صارفین مرکزی ریکویسٹ ٹیبل کو بھرے بغیر مناسب فارمیٹ منتخب کر سکیں۔

انجنز اور موڈز

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

ہر API کلید ایک انجن کے لیے ہوتی ہے: معیاری (ڈیفالٹ) یا ایڈوانسڈ، جو کلید بناتے وقت منتخب کیا جاتا ہے۔ کلید صرف اپنے انجن کی آوازیں دکھاتی اور استعمال کرتی ہے؛ دوسرا انجن استعمال کرنے کے لیے دوسری کلید بنائیں۔

  • معیاری انجن (standard) — اسٹوڈیو آوازیں جن کے تین موڈز رفتار، تاثرات اور قیمت کے درمیان توازن رکھتے ہیں۔
  • ایڈوانسڈ انجن (advanced, الفا) — اس کی اپنی آوازیں، جنہیں context، setting، style اور pace کے ساتھ سادہ زبان میں ہدایت دی جاتی ہے۔ موڈز لاگو نہیں ہوتے۔

معیاری انجن کے موڈز

mode نام کریڈٹس بہترین برائے
emotion ڈیفالٹ تاثرات اور لہجہ ×1 جذبات اور لہجوں کے ساتھ تیز، تاثراتی آواز۔ [laughing] اور [whispering] جیسے جذباتی ٹیگز کو سپورٹ کرتا ہے۔
quality اعلیٰ معیار کے تاثرات اور لہجہ ×2 مزید بھرپور اور فطری جذبات اور لہجے۔ تھوڑا زیادہ وقت لیتا ہے۔ جذباتی ٹیگز کو سپورٹ کرتا ہے۔
studio اسٹوڈیو کوالٹی ×2 مکمل وائس کنٹرول کے ساتھ صاف اور یکساں اسٹوڈیو بیانیہ۔ جذباتی ٹیگز کے بغیر۔

بغیر mode والی درخواستیں emotion موڈ میں چلتی ہیں۔

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

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

پیرامیٹر قسم رینج ڈیفالٹ تفصیل
mode اسٹرنگ (string) emotion, quality, studio emotion معیاری انجن کا موڈ۔ quality اور studio پر ×2 کریڈٹس لگتے ہیں۔ اوپر انجن اور موڈز دیکھیں۔
temperature عددی (integer) 0 – 100 25 بولنے کے اتار چڑھاؤ اور تاثرات کو کنٹرول کرتا ہے۔ کم قدریں زیادہ مستحکم اور متوقع کلام پیدا کرتی ہیں، جبکہ زیادہ قدریں تنوع، بے ساختگی اور تخلیقی انداز کو بڑھاتی ہیں۔
voice_similarity عددی (integer) 0 – 100 100 طے کرتا ہے کہ تیار کردہ کلام منتخب آواز کی پروفائل سے کس حد تک مطابقت رکھتا ہے۔ زیادہ قدریں اصل آواز کی شناخت کو برقرار رکھتی ہیں، جبکہ کم قدریں لہجے اور تلفظ میں زیادہ تبدیلی کی اجازت دیتی ہیں۔
speed اعشاری عدد (float) 0.7 – 1.2 1.0 بولنے کی رفتار کو ایڈجسٹ کرتا ہے۔ 1.0 سے کم قدریں وضاحت کے لیے کلام کو سست کرتی ہیں، جبکہ 1.0 سے زیادہ قدریں بولنے کی رفتار کو بڑھاتی ہیں۔ صرف studio موڈ کے لیے؛ emotion اور quality میں نظر انداز کر دیا جاتا ہے۔
enable_emotions متروک بولین (boolean) false / true — مطابقت کے لیے اب بھی قبول کیا جاتا ہے لیکن اب آؤٹ پٹ کو تبدیل نہیں کرتا۔ اس کے بجائے mode استعمال کریں۔
fast_mode متروک عددی (integer) 0, 1, or 2 — مطابقت کے لیے اب بھی قبول کیا جاتا ہے لیکن اب آؤٹ پٹ کو تبدیل نہیں کرتا؛ emotion موڈ پہلے ہی تیز آپشن ہے۔ ریئل ٹائم آڈیو کے لیے اسٹریمنگ اینڈ پوائنٹ استعمال کریں۔

emotion اور quality موڈز میں، temperature اور voice_similarity آواز کے کنٹرولز ہیں (رینج کے اندر کوئی بھی قدر جوں کی توں استعمال ہوتی ہے)؛ speed کا اطلاق صرف studio موڈ پر ہوتا ہے۔

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

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

ایڈوانسڈ انجن کی آوازیں mode اور معیاری انجن کے سلائیڈرز کو نظر انداز کرتی ہیں، اور مطلوبہ output_format واپس کرتی ہیں۔ تیاری میں معیاری انجن کے مقابلے میں تھوڑا زیادہ وقت لگ سکتا ہے۔

آواز کی ترتیبات کے اصول اور شرائط

  • نامعلوم کلیدیں، غیر درست mode، style یا pace، یا 500 حروف سے طویل context/setting کو 400 INVALID_REQUEST کے ساتھ مسترد کر دیا جاتا ہے۔
  • مطابقت کے لیے، جب متروک enable_emotions کی قدر true ہو تو voice_settings میں درج ذیل فیلڈز شامل نہیں ہونی چاہئیں: speed, fast_mode.

قیمتیں

کریڈٹس = حروف × (پری ریکارڈنگ ریٹ + آواز کی فیس %) × موڈ ملٹی پلائر۔ ملٹی پلائر quality اور studio کے لیے ×2، emotion کے لیے ×1، اور ایڈوانسڈ انجن کی ہر آواز کے لیے ×1.5 ہے۔

مثال

curl -X POST "https://moknah.io/api/v1/tts/generate/" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "مرحبا بك في منصة مكنة",
    "voice_id": 1,
    "prerecording": 1,
    "language": "ar",
    "voice_settings": {
        "mode": "emotion",
        "speed": 1.0,
        "temperature": 25
    }
  }' \
  --output speech.mp3

# Advanced engine voice (voice_engine = "advanced")
curl -X POST "https://moknah.io/api/v1/tts/generate/" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "مرحبا بك في منصة مكنة",
    "voice_id": 2,
    "voice_settings": {
        "context": "A warm documentary read in a Levantine dialect.",
        "pace": "slow"
    }
  }' \
  --output speech-advanced.mp3
import requests

response = requests.post(
    "https://moknah.io/api/v1/tts/generate/",
    headers={
        "Authorization": "Bearer your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "text": "مرحبا بك في منصة مكنة",
        "voice_id": 1,
        "prerecording": 1,
        "language": "ar",
        "voice_settings": {
            "mode": "emotion",
            "speed": 1.0,
            "temperature": 25
        }
    }
)

with open("speech.mp3", "wb") as f:
    f.write(response.content)
const response = await fetch(
    'https://moknah.io/api/v1/tts/generate/',
    {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer your_api_key',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            text: 'مرحبا بك في منصة مكنة',
            voice_id: 1,
            prerecording: 1,
            language: 'ar',
            voice_settings: {
                mode: 'emotion',
                speed: 1.0,
                temperature: 25
            }
        })
    }
);

const blob = await response.blob();
// Save or play the audio

جواب

مطلوبہ output_format (بطور ڈیفالٹ MP3) میں ان ہیڈرز کے ساتھ بائنری آڈیو ڈیٹا واپس کرتا ہے:

ہیڈر تفصیل
Content-Type output_format سے مطابقت رکھتا ہے: mp3_* کے لیے audio/mpeg، opus_* (Ogg/Opus) کے لیے audio/ogg، pcm_* کے لیے audio/pcm;rate=N;channels=1 (خام 16-بٹ little-endian، بغیر ہیڈر کے)۔

خرابیاں

حیثیت کوڈ تفصیل
400 INVALID_REQUEST غلط پیرامیٹرز (بشمول نامعلوم mode، style یا pace)
401 UNAUTHORIZED غلط API کلید
402 INSUFFICIENT_CREDITS کریڈٹس ناکافی ہیں
429 RATE_LIMIT_EXCEEDED بہت زیادہ درخواستیں
API سپورٹ

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