تقریر کو متن میں بدلنے کی API

یہ API مکمل آڈیو فائلوں کو قطار میں موجود جابز کے طور پر متن میں بدلتی ہے۔ فائل بھیجیں، واپس ملنے والی جاب کی شناخت محفوظ رکھیں اور عمل مکمل ہونے تک جاب حاصل کرتے رہیں۔ ہر درخواست HTTPS پر اپنے اکاؤنٹ کی اسناد کے ساتھ بھیجیں، مثالوں میں دکھائی گئی HTTP Basic اسناد یا API ٹوکن استعمال کریں، جیسا کہ اس حصے میں بیان کیا گیا ہے: توثیق۔ اسناد اپنے سرور پر رکھیں۔

اینڈ پوائنٹس

دو API میزبان، https://api.multi.tel اور مطابقت کے میزبان https://api.multitel.net، اکاؤنٹ تک محدود ایک ہی جابز، آئڈیم پوٹنسی کیز، حدود اور بلنگ استعمال کرتے ہیں۔ اپ لوڈ کی انکوڈنگ اور جواب کے بیرونی ڈھانچے میں فرق ہے، اس لیے مسلسل ایک ہی میزبان اور اس کے مطابق پارسر استعمال کریں۔

میزبان api.multi.tel پر، ہر پاتھ سابقے /v1/speech-to-text کے ساتھ بھی دستیاب ہے، جو /v3/speech_to_text کی جگہ آتا ہے، مثلاً POST /v1/speech-to-text/estimate۔ میزبان api.multitel.net پر، /v3/speech_to_text والے پاتھ استعمال کریں۔

سروس کی معلومات کا جواب یہ فیلڈز بتاتا ہے: mode (batch), realtime (false), paidEnabled (آیا اس وقت نئی بامعاوضہ جابز قبول کی جا رہی ہیں)، pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) اور maxUploadBytes (26214400)، نیز مختصر تفصیل کی فیلڈ description۔ اسے پڑھنا مفت ہے اور بامعاوضہ جابز کا ارسال بند ہونے پر بھی کام کرتا ہے؛ یہ 503 transcription_unavailable صرف تب لوٹاتا ہے جب پوری سروس دستیاب نہ ہو۔

آڈیو فائل تیار کریں

ایسی مکمل آڈیو فائل استعمال کریں جس کا حجم زیادہ سے زیادہ 25 MiB (26,214,400 بائٹس) اور دورانیہ زیادہ سے زیادہ 2 گھنٹے (7,200 سیکنڈ) ہو۔ ارسال کے وقت فائل کی شناخت MP3، WAV، Ogg، FLAC، MOV یا Matroska میڈیا کے طور پر ہونی چاہیے، اس میں آڈیو اسٹریم موجود ہو اور اس کے میٹا ڈیٹا میں دورانیہ صفر سے زیادہ اور 7,200 سیکنڈ سے زیادہ نہ ہو۔ شناخت شدہ فائل ان جانچوں پر پوری نہ اترے تو اسے 422 unsupported_audio کے ساتھ مسترد کیا جاتا ہے۔ ایسی فائل جو ان میں سے کسی فارمیٹ میں پڑھی نہ جا سکے، فی الحال اس کے بجائے سرور کی خرابی (500) کے ساتھ مسترد ہو سکتی ہے؛ ایسی فائل بغیر تبدیلی دوبارہ نہ بھیجیں۔ محض فائل کی ایکسٹینشن مطابقت ثابت نہیں کرتی۔

ان جانچوں میں کامیابی اس بات کی ضمانت نہیں کہ آڈیو ڈی کوڈ ہو سکے گی۔ آڈیو ایک یا دو چینلز کے طور پر پراسیس ہوتی ہے۔ دو سے زیادہ آڈیو چینلز والی فائل، ایسی فائل جس کی ڈی کوڈ شدہ آڈیو 2 گھنٹے سے زیادہ ہو، یا کوئی دوسری فائل جس کی ڈی کوڈنگ دورانِ عمل ناکام ہو، ایسی جاب کے طور پر ختم ہوتی ہے جس کی حالت failed ہوتی ہے، عموماً خرابی decode_failed کے ساتھ، اور اس کا معاوضہ نہیں لیا جاتا۔ ارسال سے پہلے متعدد چینلز والی آڈیو کو مونو یا اسٹیریو میں بدلیں۔

اختیاری زبان کا اشارہ بولی گئی زبان کا دو یا تین چھوٹے حروف پر مشتمل کوڈ ہے، مثلاً en۔ اشارہ نہ دینا ہو تو فیلڈ شامل نہ کریں؛ api.multi.tel خالی اسٹرنگ مسترد کرتا ہے۔ اشارہ عمل کی رہنمائی کرتا ہے لیکن اسے معاون زبانوں کی فہرست سے نہیں ملایا جاتا، اس لیے بولی گئی زبان کا درست کوڈ استعمال کریں۔

آڈیو کو متن میں بدلنے کی جاب بھیجیں

JSON کو Content-Type: application/json کے ساتھ اس پتے پر بھیجیں: POST https://api.multi.tel/v3/speech_to_text۔ درخواست کی باڈی زیادہ سے زیادہ 35 MiB ہو سکتی ہے، تاکہ base64 انکوڈنگ کے بعد زیادہ سے زیادہ حجم کی فائل سما سکے؛ بڑی باڈی 413 کے ساتھ مسترد ہوتی ہے۔

کوئی بھی دوسری JSON پراپرٹی، بشمول idempotency_key، 400 invalid_transcription_request کے ساتھ مسترد ہوتی ہے۔ کی کو ہیڈر میں بھیجیں۔

آئڈیم پوٹنسی کی

ہر ارسال کے لیے Idempotency-Key ہیڈر درکار ہے جس کی لمبائی 1 سے 190 حروف ہو۔ ASCII حروف، ہندسے، -, _, . اور : استعمال کریں، شروع یا آخر میں خالی جگہیں نہ ہوں: مطابقت کا میزبان اردگرد کی خالی جگہیں ہٹاتا اور کی کو بائٹس میں ناپتا ہے، اس لیے دوسرے حروف ہر میزبان پر مختلف طرح گنے جا سکتے ہیں۔ غائب کی، یا 191 یا زیادہ حروف کی کی، 400 کے ساتھ مسترد ہوتی ہے۔

کیز آپ کے اکاؤنٹ اور تقریر کو متن میں بدلنے کی سروس تک محدود ہیں، دونوں میزبانوں اور اکاؤنٹ کی تمام اسناد پر۔ اسی کی کو اسی فائل اور زبان کے ساتھ دوبارہ بھیجنے پر موجودہ جاب HTTP 200 اور duplicate: true کے ساتھ ملتی ہے، چاہے اس کی حالت کچھ بھی ہو اور چاہے جاب بننے کے بعد پراسیسنگ اپ ڈیٹ ہو چکی ہو، کوئی اضافی معاوضہ نہیں لیا جاتا۔ اسی کی کو مختلف فائل یا زبان کے ساتھ استعمال کرنے پر 409 idempotency_conflict ملتا ہے۔ نئی کی یکساں فائل کے لیے بھی نئی جاب بناتی ہے، جس کا عمل کامیابی سے مکمل ہونے پر الگ معاوضہ لیا جاتا ہے۔

API_USER="your-api-username"
API_PASSWORD="your-api-password"

node -e 'process.stdout.write(JSON.stringify({audioBase64:require("node:fs").readFileSync("completed-call.mp3").toString("base64"),language:"en"}))' > completed-call.json

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: speech-call-001" \
  --data-binary @completed-call.json \
  -o speech-job.json \
  https://api.multi.tel/v3/speech_to_text

node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id'

نئی جاب HTTP 202 کے ساتھ نیچے دکھائی گئی فیلڈز لوٹاتی ہے، اور دوبارہ ارسال پر HTTP 200 کے ساتھ جاب کا مکمل آبجیکٹ ملتا ہے، جو اس حصے میں بیان ہوا ہے: آڈیو کا متن پڑھیں۔ جاب کی شناخت، جو UUID ہے، data.id سے پڑھیں۔ نئی جاب کا جواب اس طرح دکھائی دیتا ہے (شناخت اور قدریں مثالیں ہیں):

{
  "status": "success",
  "data": {
    "id": "3f6c1b2e-8a4d-4e7f-9c21-5b0d7e4a9f13",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "source": "api",
    "durationSeconds": 90.5,
    "billedSeconds": 91,
    "costUsd": "0.007583334",
    "pricePerMinuteUsd": "0.005"
  }
}

جب جاب قطار میں ہو یا چل رہی ہو تو durationSeconds, billedSeconds اور costUsd فائل کے میٹا ڈیٹا سے حاصل کردہ تخمینے ہوتے ہیں۔ حتمی معاوضہ ڈی کوڈ شدہ دورانیے پر مبنی ہوتا ہے۔

ارسال پر 402 insufficient_balance بھی مل سکتا ہے جب پیشگی ادا شدہ بیلنس اس جاب اور آپ کی دیگر نامکمل جابز کی مجموعی لاگت کے لیے کافی نہ ہو، 429 transcription_queue_full جب آپ کے اکاؤنٹ یا سروس میں بہت زیادہ نامکمل جابز ہوں، 429 audio_validation_busy جب فائل کی جانچ کی گنجائش پوری ہو، اور 503 paid_transcription_not_enabled جب بامعاوضہ آڈیو سے متن کی سروس بند ہو۔ 429 اور 503 کے جوابات پر بعد میں اسی کی کے ساتھ دوبارہ کوشش کریں۔

جاب بنائے بغیر تخمینہ لگائیں

وہی JSON باڈی اس پتے پر بھیجیں: POST https://api.multi.tel/v3/speech_to_text/estimate۔ آئڈیم پوٹنسی کی درکار نہیں۔ تخمینہ فائل کی جانچ اور پیمائش کرتا ہے مگر اسے متن میں نہیں بدلتا، جاب نہیں بناتا، رقم محفوظ نہیں کرتا، آپ کا بیلنس نہیں دیکھتا اور اکاؤنٹ سے معاوضہ نہیں لیتا۔ language کا اشارہ قبول ہوتا ہے مگر تخمینے پر اثر نہیں ڈالتا۔

کامیاب تخمینہ HTTP 200 لوٹاتا ہے، جس میں estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd اور costUsd، data کے تحت ہوتے ہیں۔ یہ فائل کے میٹا ڈیٹا کا دورانیہ استعمال کرتا ہے، جبکہ مکمل جاب کا معاوضہ ڈی کوڈ شدہ دورانیے پر لیا جاتا ہے، جو مختلف ہو سکتا ہے۔ تخمینے ارسال والی ہی فائل جانچیں لاگو کرتے ہیں۔ یہ صرف بامعاوضہ آڈیو سے متن کی سروس فعال ہونے پر دستیاب ہیں (ورنہ 503 paid_transcription_not_enabled)۔ یہ 429 audio_validation_busy لوٹا سکتے ہیں جب فائل کی جانچ کی گنجائش پوری ہو؛ تھوڑی دیر انتظار کر کے دوبارہ کوشش کریں۔

آڈیو کا متن پڑھیں

وقفے وقفے سے GET /v3/speech_to_text/JOB_ID حاصل کریں، جیسا کہ جاب کے طریقۂ کار کی رہنما دستاویز میں بیان ہوا ہے۔ جاب کے آبجیکٹ میں یہ فیلڈز شامل ہیں:

آڈیو کے متن، اس کے وقت کے نشانات، زبان اور چینل کے لیبل خودکار طور پر بنتے ہیں اور ان کی درستگی کی ضمانت نہیں۔ معیار کے کسی بھی نشان کو نتیجہ جانچنے کی وجہ سمجھیں، اور اہم ناموں، نمبروں اور وعدوں کا اصل آڈیو سے موازنہ کریں۔ طویل خاموشی اور بہت دھیمی آواز والے حصے چھوڑ دیے جاتے ہیں اور ان کے لیے کوئی حصے نہیں بنتے۔ نتائج انفرادی بولنے والوں کی شناخت نہیں کرتے۔ جب نتیجے میں channelCount کی قدر 2 ہو تو ہر حصے میں channel کی قدر A (پہلا، یا بایاں، چینل) یا B (دوسرا، یا دایاں، چینل) ہوتی ہے۔ اس سے بولنے والے صرف تب الگ ہوتے ہیں جب ہر شخص الگ چینل پر ریکارڈ ہوا ہو۔ دو چینلز کی آڈیو کا معاوضہ اس کے گزرے ہوئے دورانیے پر ایک بار لیا جاتا ہے، ہر چینل پر الگ نہیں۔ مونو نتائج میں چینل لیبل نہیں ہوتے۔

api.multitel.net کا استعمال

مطابقت کا اینڈ پوائنٹ POST https://api.multitel.net/v3/speech_to_text، multipart/form-data قبول کرتا ہے، جس میں audio نام کا فائل حصہ اور اختیاری language فیلڈ ہوتی ہے، JSON کی audioBase64 کے بجائے۔ خالی language کو کوئی اشارہ نہ دینے کے برابر سمجھا جاتا ہے۔ وہی Idempotency-Key ہیڈر بھیجیں۔ اگر ہیڈر غائب ہو تو یہ میزبان idempotency_key فارم فیلڈ بھی قبول کرتا ہے۔ source, free, billing_source, realtime یا stream نام کی فیلڈز 400 unsupported_transcription_option کے ساتھ مسترد ہوتی ہیں؛ دیگر فارم فیلڈز نظرانداز ہوتی ہیں۔ یہ میزبان یہ خرابیاں بھی لوٹاتا ہے:

• 400 idempotency_key_required غائب یا حد سے لمبی کی کے لیے۔
• 400 audio_upload_required غائب اپ لوڈ، یا ایسا اپ لوڈ جو مکمل وصول نہ ہوا ہو۔
• 400 invalid_language غلط زبان کے لیے۔
• 413 invalid_audio_size خالی یا حد سے بڑی فائل کے لیے۔
• 400 invalid_job غلط ساخت کی جاب شناخت کے لیے۔

اس میزبان کی تقریر کو متن میں بدلنے والی سروس کے جوابات یہ بیرونی ڈھانچہ استعمال کرتے ہیں: {"status":{"code":HTTP_STATUS},"response":{...}}۔ یاد رکھیں کہ status آبجیکٹ ہے، اسٹرنگ نہیں۔ کامیابی پر response میں وہی آبجیکٹ ہوتا ہے جو data میں بنیادی میزبان پر ہوتا ہے، اس لیے جاب کی شناخت response.id ہے۔ خرابی پر response.code میں خرابی کا کوڈ ہوتا ہے؛ پیغام یا درخواست کی شناخت شامل نہیں ہوتی۔ توثیق کی ناکامیاں (401) میزبان کی عمومی سائن اِن جانچ سے لوٹتی ہیں اور ان کی باڈی مختلف ہو سکتی ہے، اس لیے پارس کرنے سے پہلے HTTP اسٹیٹس دیکھیں۔ میزبانوں کے درمیان اپ لوڈ انکوڈنگ یا جواب کا پارسر بدل کر استعمال نہ کریں۔

اس میزبان پر تخمینے کے لیے وہی multipart فیلڈز POST کے ذریعے اس پتے پر بھیجیں: /v3/speech_to_text/estimate۔ آئڈیم پوٹنسی کی درکار نہیں، اور تخمینہ response کے تحت ہے۔

API_USER="your-api-username"
API_PASSWORD="your-api-password"

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Idempotency-Key: speech-call-001" \
  -F "audio=@completed-call.mp3" -F "language=en" \
  -o speech-job.json \
  https://api.multitel.net/v3/speech_to_text

node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).response.id'