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

مضمون سے آواز (ATS)

مکمل مضمون کو بیان کردہ آڈیو اور ٹرانسکرپشن میں تبدیل کریں، جو غیر مطابقت پذیر طور پر آپ کے callback URL پر بھیجے جاتے ہیں۔

POST https://api.moknah.io/process-text

مضمون سے آواز (ATS) اینڈ پوائنٹ مضمون کا متن قبول کرتا ہے اور ایک ہم آہنگ ٹرانسکرپشن (.srt) فائل کے ساتھ MP3 آڈیو تیار کرتا ہے۔ یہ عمل غیر مطابقت پذیر طور پر چلتا ہے: درخواست فوری طور پر 202 Accepted واپس کرتی ہے، اور مکمل فائلیں آپ کے فراہم کردہ callbackURL پر پہنچا دی جاتی ہیں۔ یہ وہی سروس ہے جو ATS WordPress پلگ ان کو چلاتی ہے۔

ڈیزائن کے لحاظ سے غیر مطابقت پذیر

اپنی آڈیو کے لیے HTTP رسپانس کا انتظار نہ کریں۔ اینڈ پوائنٹ فوری طور پر 202 کا جواب دیتا ہے اور تیاری مکمل ہونے پر آپ کے callbackURL پر نتیجہ POST کر دیتا ہے۔

تصدیق

Authorization ہیڈر میں اپنی کمپنی کی API کلید کو بطور Bearer ٹوکن شامل کریں۔

Authorization: Bearer your_api_key

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

مضمون کے خام متن اور درخواست کی وضاحت کرنے والے postData آبجیکٹ کے ساتھ JSON باڈی بھیجیں۔

پیرامیٹر لازمی قسم تفصیل
text لازمی اسٹرنگ (string) مضمون کا مکمل متن جسے آواز میں تبدیل کرنا ہے۔
postData لازمی آبجیکٹ (object) درخواست کا میٹا ڈیٹا۔ نیچے دیے گئے فیلڈز دیکھیں۔

postData آبجیکٹ

فیلڈ لازمی قسم ڈیفالٹ تفصیل
name لازمی اسٹرنگ (string) — مضمون کا عنوان۔ تیار کردہ آڈیو درخواست کے عنوان کے طور پر استعمال ہوتا ہے۔
articleId لازمی اسٹرنگ (string) — مضمون کے لیے آپ کا منفرد شناخت کنندہ۔ یہ idempotency کلید کے طور پر کام کرتا ہے (نیچے Idempotency دیکھیں) اور کال بیک میں واپس بھیجا جاتا ہے۔
voiceId لازمی اسٹرنگ (string) — بیان کرنے کے لیے آواز۔ اس میں سے ایک ID استعمال کریں: آوازوں کی فہرست. اپنی کمپنی کی API کلید کی قسم کی آواز استعمال کریں: معیاری کلید معیاری آوازیں (voice_engine = standard) اور ایڈوانسڈ کلید ایڈوانسڈ آوازیں (voice_engine = advanced) استعمال کرتی ہے۔ قسم آپ کلید بناتے وقت منتخب کرتے ہیں۔ دونوں صورتوں میں .srt فائل کا ہر جملہ لفظ بہ لفظ وقت کے ساتھ ہوتا ہے۔
callbackURL لازمی اسٹرنگ (URL) — وہ HTTPS URL جہاں Moknah مکمل شدہ آڈیو اور ٹرانسکرپشن کے URLs کو POST کرے گا۔ کمپنی کے لیے تازہ ترین ویلیو محفوظ کی جاتی ہے۔
preprocessType اختیاری اسٹرنگ (string) "0" متن کی تیاری کا موڈ: بغیر کسی تبدیلی (لفظ بہ لفظ بیان) کے لیے "0" یا عربی تشکیل کے لیے "2" (AI اعراب لگاتا ہے اور اعداد کو الفاظ میں لکھتا ہے؛ حروف کی لاگت دگنی ہو جاتی ہے)۔ اسٹرنگ یا عدد دونوں قبول ہیں۔ "2" صرف عربی کے لیے دستیاب ہے، اور AI کو صرف عربی جملے بھیجے جاتے ہیں۔
language اختیاری اسٹرنگ (string) "auto" مواد کی زبان: "auto" یا کوئی ISO 639-1 کوڈ، جیسے "ar" یا "en"۔ "auto" کے ساتھ preprocessType "2" صرف اسی وقت استعمال ہوتا ہے جب متن عربی ہو؛ ورنہ مضمون "0" کی طرح بیان کیا جاتا ہے اور ایک ہی بار چارج ہوتا ہے۔ عربی کے علاوہ کسی اور زبان کے ساتھ "2" بھیجنے پر درخواست 422 VALIDATION_ERROR کے ساتھ مسترد کر دی جاتی ہے۔
regenerate اختیاری بولین (boolean) false جب true ہو، تو یہ نئے سرے سے آڈیو تیار کرنے پر مجبور کرتا ہے چاہے یہ articleId پہلے تیار کیا جا چکا ہو۔

درخواست کی مثال

curl -X POST "https://api.moknah.io/process-text" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.",
    "postData": {
        "name": "AI is evolving fast",
        "articleId": "post-123",
        "voiceId": "12",
        "callbackURL": "https://your-site.com/wp-json/ats/v1/callback",
        "preprocessType": "0",
        "language": "auto",
        "regenerate": false
    }
  }'
import requests

response = requests.post(
    "https://api.moknah.io/process-text",
    headers={
        "Authorization": "Bearer your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "text": "الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.",
        "postData": {
            "name": "AI is evolving fast",
            "articleId": "post-123",
            "voiceId": "12",
            "callbackURL": "https://your-site.com/wp-json/ats/v1/callback",
            "preprocessType": "0",
            "language": "auto",
            "regenerate": False
        }
    }
)

# 202 Accepted — the audio is delivered to your callbackURL
print(response.status_code, response.text)
const response = await fetch(
    'https://api.moknah.io/process-text',
    {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer your_api_key',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            text: 'الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.',
            postData: {
                name: 'AI is evolving fast',
                articleId: 'post-123',
                voiceId: '12',
                callbackURL: 'https://your-site.com/wp-json/ats/v1/callback',
                preprocessType: '0',
                language: 'auto',
                regenerate: false
            }
        })
    }
);

// 202 Accepted — result arrives at your callbackURL

فوری رسپانس

اگر درخواست قبول کر لی جاتی ہے، تو اینڈ پوائنٹ فوری طور پر جواب دیتا ہے:

Processing started. Results will be sent to the callback URL.

کال بیک پے لوڈ (Callback Payload)

جب تیاری مکمل ہو جاتی ہے، تو Moknah اس JSON باڈی کے ساتھ آپ کے callbackURL پر ایک POST درخواست بھیجتا ہے:

{
    "articleId": "post-123",
    "response": {
        "audioFile": "https://api-storage.moknah.io/.../******.mp3",
        "srtFile": "https://api-storage.moknah.io/.../******.srt",
        "signature": "<hmac-sha256-hex>"
    }
}
فیلڈ تفصیل
articleId وہی articleId جو آپ نے درخواست میں بھیجا تھا۔
response.audioFile تیار کردہ MP3 نریشن کا عوامی URL، یا اگر تیاری ناکام ہو گئی ہو تو null۔
response.srtFile ہم آہنگ ٹرانسکرپشن (.srt) فائل کا عوامی URL، یا اگر تیاری ناکام ہو گئی ہو تو null۔
response.signature HMAC-SHA256 دستخط جسے آپ پے لوڈ کے مستند ہونے کی تصدیق کے لیے استعمال کر سکتے ہیں (نیچے دیکھیں)۔
ناکام جنریشنز سے نمٹنا

جب جنریشن سے کوئی آڈیو بنتی نہیں ہے تو تب بھی ایک کال بیک بھیجا جاتا ہے۔ اس صورت میں response.audioFile اور response.srtFile کی قدر null ہوتی ہے (دستخط اب بھی articleId|null|null کا احاطہ کرتا ہے)۔ ایسے کسی بھی کال بیک کو جس میں audioFile یا srtFile کی قدر null ہو، ناکامی کے طور پر لیں: مضمون کو مکمل نشان زد نہ کریں، اور regenerate کو true پر سیٹ کر کے اسے دوبارہ بھیجیں۔

دستخط کی تصدیق کرنا

یہ دستخط اسٹرنگ articleId|audioFile|srtFile کا ایک HMAC-SHA256 (hex) ہے، جسے آپ کی API کلید کے SHA-256 hex ڈائجسٹ کے ساتھ کلید بند کیا گیا ہے۔ اپنی طرف اس کا دوبارہ حساب لگائیں اور موازنہ کریں تاکہ تصدیق ہو سکے کہ کال بیک Moknah کی طرف سے آیا ہے اور اس میں کوئی چھیڑ چھاڑ نہیں کی گئی۔

import crypto from 'crypto';

const keyHash = crypto.createHash('sha256').update(API_KEY).digest('hex');
const payload = `${articleId}|${audioFile}|${srtFile}`;
const expected = crypto.createHmac('sha256', keyHash).update(payload).digest('hex');

const isValid = expected === signature;
import hashlib, hmac

key_hash = hashlib.sha256(API_KEY.encode()).hexdigest()
payload = f"{article_id}|{audio_file}|{srt_file}"
expected = hmac.new(key_hash.encode(), payload.encode(), hashlib.sha256).hexdigest()

is_valid = hmac.compare_digest(expected, signature)

آئیڈیمپوٹینسی اور دوبارہ تیاری (Regeneration)

  • درخواستوں کو ہر کمپنی کے لحاظ سے articleId کے ذریعے شناخت کیا جاتا ہے۔ ایک نیا articleId نئی جنریشن شروع کرتا ہے۔
  • اگر کوئی مضمون اس وقت تیار کیا جا رہا ہو، تو بار بار کی جانے والی درخواستیں 409 ALREADY_PROCESSING کے ساتھ مسترد کر دی جاتی ہیں۔
  • اگر کوئی مضمون پہلے ہی تیار کیا جا چکا ہو اور regenerate کی قدر false ہو، تو موجودہ آڈیو کو دوبارہ تیار کیے بغیر (اور دوبارہ چارج کیے بغیر) آپ کے callbackURL پر دوبارہ بھیج دیا جاتا ہے۔
  • کسی موجودہ articleId کے لیے بالکل نئی جنریشن کو لازمی کرنے کے لیے regenerate کو true پر سیٹ کریں۔
  • اگر کسی articleId کی پچھلی کوشش ناکام ہوئی تھی تو اسے دوبارہ بھیجنے پر وہ پھر سے تیار ہو جاتا ہے؛ نئے articleId کی ضرورت نہیں۔

بیک وقت عمل آوری (Concurrency) اور کارکردگی

مضامین ایک قطار سے تیار کیے جاتے ہیں جس میں ہر کلائنٹ کو منصفانہ حصہ ملتا ہے۔ آپ ایک ساتھ کئی مضامین بھیج سکتے ہیں: سب قبول کیے جاتے ہیں، چند چند کر کے تیار ہوتے ہیں، اور ہر مضمون تیار ہوتے ہی آپ کے callback URL پر بھیج دیا جاتا ہے۔

  • اس لیے بڑا بیچ ایک ساتھ نہیں بلکہ بتدریج مکمل ہوتا ہے؛ آپ کو اپنی طرف سے مضامین روک کر رکھنے کی ضرورت نہیں۔
  • کسی بھی ناکام مضمون کو regenerate کی قدر true رکھ کر دوبارہ کوشش کریں؛ پہلے سے تیار شدہ مضامین کیشے (cache) میں محفوظ ہوتے ہیں اور انہیں دوبارہ بھیجنے کی ضرورت نہیں ہوتی۔
  • /process-text اینڈ پوائنٹ پر بھی ہر کلائنٹ کے لحاظ سے ریٹ کی حد مقرر ہے؛ حد سے تجاوز کرنے والی تیز درخواستوں کو 429 Too Many Requests موصول ہوتا ہے، اس لیے اپنی درخواستوں کے درمیان وقفہ رکھیں یا انہیں بیچز کی صورت میں بھیجیں۔

بلنگ

حروف کی لاگت کا حساب text میں موجود حروف کی تعداد کو پری پروسیسنگ فیکٹر سے ضرب دے کر لگایا جاتا ہے (بطور ڈیفالٹ 1، اور جب preprocessType کی قدر 2 ہو تو 2)۔ کریڈٹس صرف تب کاٹے جاتے ہیں جب جنریشن درحقیقت چلتی ہے۔ پہلے سے تیار کردہ مضمون کی دوبارہ ترسیل مفت ہے، اور اگر جنریشن یا ترسیل ناکام ہو جائے تو کاٹے گئے کریڈٹس خودکار طور پر واپس کر دیے جاتے ہیں۔

ایڈوانسڈ آوازوں (voice_engine = advanced) پر پری پروسیسنگ کے ضرب کے علاوہ ایڈوانسڈ موڈ کی شرح سے چارج کیا جاتا ہے۔

خرابیاں

حیثیت کوڈ تفصیل
401 AUTH_FAILED Authorization ہیڈر غائب ہے یا API کلید غلط ہے۔
422 VALIDATION_ERROR متن غائب ہے، یا postData کے خانے غلط/غائب ہیں۔
400 INVALID_VOICE_ID فراہم کردہ voiceId موجود نہیں ہے۔
400 UNSUPPORTED_VOICE یہ آواز آپ کی API کلید کی قسم (معیاری یا ایڈوانسڈ) کی نہیں ہے، یا ابھی دستیاب نہیں ہے۔
409 ALREADY_PROCESSING یہ مضمون پہلے ہی تیار کیا جا رہا ہے۔ مکمل ہونے کے بعد دوبارہ کوشش کریں۔
422 PROCESSING_ERROR جنریشن ناکام ہو گئی۔ کاٹے گئے تمام کریڈٹس واپس کر دیے جاتے ہیں۔
422 REFUND_FAILED پروسیسنگ ناکام ہو گئی اور خودکار واپسی مکمل نہیں ہو سکی۔ api@moknah.io پر رابطہ کریں۔
API سپورٹ

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