گفتار اور ترجمے کے ٹاسک

ذیل میں SERVICE کی جگہ speech_to_text یا translate، اور JOB_ID کی جگہ واپس ملنے والا UUID رکھیں۔ تمام کارروائیوں کے لیے آپ کے اکاؤنٹ کی اسناد ضروری ہیں، جیسا کہ توثیق میں بیان کیا گیا ہے، اور ان کا دائرہ مالک اکاؤنٹ تک محدود ہے۔ ٹاسک دونوں میں سے کسی بھی API ہوسٹ سے پڑھا جا سکتا ہے، لیکن ہر ہوسٹ جواب کی اپنی بیرونی ساخت استعمال کرتا ہے، اس لیے مستقل طور پر ایک ہی ہوسٹ استعمال کریں۔

ہوسٹ api.multitel.net پر توثیق کی ناکامیاں (401) اس بیرونی ساخت کے اطلاق سے پہلے واپس آتی ہیں اور ان کا متن مختلف ہو سکتا ہے، اس لیے جواب کو پارس کرنے سے پہلے HTTP اسٹیٹس دیکھیں۔

توثیق

ہر درخواست میں آپ کے اکاؤنٹ کی اسناد ہونی چاہئیں۔ ٹاسک، آئیڈیمپوٹینسی کیز، حدود، استعمال اور چارجز اس اکاؤنٹ کے ہوتے ہیں جو اسناد کا مالک ہے۔ دونوں ہوسٹس پر اس اکاؤنٹ کی تمام اسناد کے لیے یہ مشترک ہیں، چاہے درخواست کسی بھی سند سے بھیجی جائے۔

• HTTP Basic (Authorization: Basic یا curl --user)۔ پاس ورڈ کی قسم کے API اکاؤنٹ، ذیلی اکاؤنٹ، یا آپ کے اکاؤنٹ کی لاگ اِن اسناد قبول کی جاتی ہیں۔ ہم ایک مخصوص API اکاؤنٹ تجویز کرتے ہیں۔ صارف نام میں کولن نہیں ہو سکتا، اور صارف نام اور پاس ورڈ میں سے کوئی بھی خالی نہیں ہو سکتا۔
• Bearer ٹوکن (Authorization: Bearer YOUR_TOKEN)۔ ٹوکن کی قسم کے API اکاؤنٹ کے لیے قبول کیا جاتا ہے۔ ٹوکن والے API اکاؤنٹس پر IP کی پابندی ضروری ہے اور درخواستیں اجازت یافتہ پتے سے آنی چاہئیں۔ دونوں API ہوسٹس اکاؤنٹ کے لیے مقرر کردہ IPv4 پتے اور CIDR رینجز قبول کرتے ہیں۔ ٹوکن کو Basic پاس ورڈ کے طور پر نہیں بھیجا جا سکتا۔ تصدیق کریں کہ آپ کا ٹوکن اس ہوسٹ پر کام کرتا ہے جسے آپ استعمال کرتے ہیں۔

API_TOKEN="your-api-token"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.multi.tel/v3/speech_to_text

اگر API اکاؤنٹ پر IP پتے کی پابندی ہے تو اجازت یافتہ پتے سے درخواستیں بھیجیں۔ اسناد غائب یا غلط ہوں تو 401 واپس آتا ہے۔ ہوسٹ api.multitel.net پر درست اسناد جو یہ خدمات استعمال نہیں کر سکتیں، مثلاً ٹوکن اکاؤنٹ کی اسناد جو Basic کے طور پر بھیجی جائیں، 403 کے ساتھ unsupported_transcription_principal یا unsupported_translation_principal واپس کرتی ہیں۔ ہوسٹ api.multitel.net پر ایک پتے سے توثیق کی بار بار ناکامی اس پتے کو بلاک کر سکتی ہے، اس لیے دوبارہ کوشش سے پہلے اسناد درست کریں۔

مکمل ہونے تک ٹاسک کی حالت پوچھیں

درخواست بھیجیں: GET /v3/SERVICE/JOB_ID۔ ہم ہر 3 سیکنڈ میں زیادہ سے زیادہ ایک بار حالت پوچھنے کی سفارش کرتے ہیں۔ بیرونی ساخت درخواست کو بیان کرتی ہے؛ کارروائی مکمل ہوئی یا نہیں جاننے کے لیے اس کے اندر ٹاسک کا status دیکھیں۔

API_USER="your-api-username"
API_PASSWORD="your-api-password"
SERVICE="speech_to_text"
HOST="https://api.multi.tel"
JOB_ID=$(node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id')

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/$JOB_ID"

ہوسٹ api.multitel.net پر HOST کو https://api.multitel.net پر مقرر کریں اور .response.id پڑھیں، بجائے .data.id کے۔

غیر یقینی نتیجے والی درخواستیں محفوظ طریقے سے دوبارہ بھیجیں

اگر ٹاسک بھیجتے وقت مقررہ انتظار ختم ہو جائے یا 429 یا 5xx اسٹیٹس واپس آئے تو وہی اِن پٹ اسی آئیڈیمپوٹینسی کلید کے ساتھ دوبارہ بھیجیں۔ کام قبول ہونے کے بعد کسی بھی ہوسٹ کا جواب ضائع ہو سکتا ہے یا اس کی جگہ خرابی آ سکتی ہے؛ اسی کلید سے دوبارہ بھیجنے پر ٹاسک موجود ہو تو واپس ملتا ہے۔ کلید کو مختلف اِن پٹ کے ساتھ دوبارہ استعمال کرنے سے 409 کے ساتھ idempotency_conflict واپس آتا ہے۔ کچھ خرابیاں ہر کوشش پر آتی ہیں، مثلاً بامعاوضہ خدمت بند ہونے پر 503 یا ناقابل مطالعہ آڈیو فائل کے لیے 500، اس لیے چند کوششوں کے بعد رک جائیں۔

کلید بدلنے کے اثرات ہر خدمت کے لیے مختلف ہیں۔

• گفتار کو متن میں بدلنے کے لیے نئی کلید نیا ٹاسک بناتی ہے، جس کی پراسیسنگ کامیاب ہونے پر الگ چارج لیا جاتا ہے۔ پراسیسنگ اپ ڈیٹ ہونے کے بعد بھی اصل کلید اصل ٹاسک ہی واپس کرتی رہتی ہے۔
• ترجمے کے لیے یکساں مواد کے ساتھ نئی کلید بغیر نئے چارج کے مماثل ٹاسک واپس کرتی ہے جو قطار میں ہو، پراسیس ہو رہا ہو، مکمل ہو چکا ہو یا ادائیگی کا منتظر ہو۔ نیا کام تب بنتا ہے جب پچھلا ٹاسک ناکام ہو یا پراسیسنگ کا ورژن بدل گیا ہو۔ پراسیسنگ ورژن بدلنے کے بعد اصل کلید سے ترجمے کی دوبارہ کوشش 409 واپس کرتی ہے، اس لیے اصل ٹاسک ID محفوظ رکھیں اور ٹاسک براہ راست پڑھیں۔

بیلنس بڑھانے کے بعد نتیجہ حاصل کریں

اگر ٹاسک کی حالت awaiting_payment ہے تو اتنی رقم شامل کریں کہ بیلنس کم از کم ٹاسک کی costUsd قدر کو اوپر کی جانب $0.00001 کے اگلے مضرب تک راؤنڈ کرنے کے بعد ملنے والی رقم ہو، پھر بھیجیں: POST /v3/SERVICE/JOB_ID/settle۔ کٹوتیاں $0.00001 کی مکمل اکائیوں میں ہوتی ہیں اور اسی خدمت کے پچھلے ٹاسکس سے منتقل ہونے والا باقی ماندہ حصہ بھی شامل ہوتا ہے، اس لیے کٹی ہوئی رقم costUsd سے زیادہ ہو سکتی ہے، مگر یہ فرق $0.00001 سے کم ہوتا ہے۔ ہوسٹ api.multi.tel پر JSON {} یا خالی باڈی بھیجیں؛ باڈی میں کوئی بھی خاصیت 400 کے ساتھ مسترد ہوتی ہے۔ ہوسٹ api.multitel.net باڈی کو نظر انداز کرتا ہے۔ تصفیہ محفوظ نتیجہ فراہم کرتا ہے اور نقل نویسی یا ترجمہ دوبارہ نہیں چلاتا۔ جواب میں ٹاسک ہوتا ہے؛ دیکھیں کہ اس کی حالت completed ہے۔ بیلنس اب بھی ناکافی ہو تو ٹاسک کی حالت awaiting_payment رہتی ہے اور جواب پھر بھی HTTP 200 ہوتا ہے۔

گفتار کو متن میں بدلنے کے لیے پہلے سے مکمل ٹاسک کی ادائیگی کا تصفیہ اسے duplicate: true کے ساتھ واپس کرتا ہے، جبکہ قطار میں، پراسیسنگ میں یا ناکام ٹاسک کا تصفیہ 409 کے ساتھ transcription_not_awaiting_payment واپس کرتا ہے۔ ترجمے کے لیے کسی بھی دوسری حالت میں ٹاسک کا تصفیہ ٹاسک کو بغیر تبدیلی واپس کرتا ہے۔ تصفیہ صرف اس وقت دستیاب ہے جب بامعاوضہ پراسیسنگ فعال ہو (ورنہ 503)۔ ادائیگی کے منتظر ٹاسک مختص لاگت میں شمار ہوتے ہیں، اس لیے پری پیڈ اکاؤنٹس میں تصفیہ ہونے تک وہ نئے بامعاوضہ ٹاسک بھیجنے کو 402 کے ساتھ روک سکتے ہیں۔

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -X POST -H "Content-Type: application/json" --data '{}' \
  "$HOST/v3/$SERVICE/$JOB_ID/settle"

استعمال دیکھیں

استعمال کریں: GET /v3/SERVICE/usage۔ اختیاری پیرامیٹرز from اور to UTC تاریخیں ہیں جن کا فارمیٹ YYYY-MM-DD ہے، اور دونوں سرحدی تاریخیں شامل ہوتی ہیں۔ نہ دینے پر from کی پہلے سے طے شدہ قدر آج سے 30 دن پہلے کی تاریخ اور to کی قدر آج کی تاریخ (UTC) ہوتی ہے۔ to کی تاریخ from سے پہلے نہیں ہو سکتی، اور تاریخوں کا فرق زیادہ سے زیادہ 366 دن (زیادہ سے زیادہ 367 تاریخیں) ہو سکتا ہے۔ غلط کیلنڈر تاریخیں، الٹی یا زیادہ طویل رینج 400 واپس کرتی ہیں، اور ہوسٹ api.multi.tel پر دیگر کوئری پیرامیٹرز بھی یہی کرتے ہیں۔

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/usage?from=2026-10-01&to=2026-10-31"

جواب میں mode، currency (USD)، from، to اور days ہوتے ہیں؛ آخری قدر نئی سے پرانی ترتیب میں فہرست ہے۔

• گفتار کو متن میں بدلنے کے اندراجات تاریخ اور ماخذ کے لحاظ سے گروپ ہوتے ہیں۔ ان میں date، source (api یا hpbx، Hosted PBX ریکارڈنگز کے لیے)، files، audioSeconds، billedSeconds، accruedUsd اور debitedUsd ہوتے ہیں۔
• ترجمے کے اندراجات تاریخ، ماخذ اور انجن کے لحاظ سے گروپ ہوتے ہیں۔ ان میں date، source، engine، jobs، sourceCharacters، accruedUsd اور debitedUsd ہوتے ہیں۔

accruedUsd اعشاریے کے بعد نو ہندسوں تک درست لاگت ہے، اور debitedUsd اعشاریے کے بعد پانچ ہندسوں والی کٹی ہوئی رقم ہے۔ استعمال ہر ٹاسک کے چارج کا تصفیہ ہونے کی UTC تاریخ پر درج ہوتا ہے، اس لیے قطار میں، پراسیسنگ میں، ناکام اور ادائیگی کے منتظر ٹاسک نظر نہیں آتے۔

حدود

ہر اکاؤنٹ میں گفتار کو متن میں بدلنے اور ترجمے کے مجموعی طور پر زیادہ سے زیادہ 50 نامکمل ٹاسک ہو سکتے ہیں: قطار میں، پراسیسنگ میں یا ادائیگی کے منتظر، بشمول Hosted PBX ریکارڈنگز کا کام۔ یہ حد یا خدمت کی مجموعی گنجائش پوری ہونے پر ٹاسک بھیجنے سے 429 کے ساتھ transcription_queue_full یا translation_queue_full واپس آتا ہے۔ ہوسٹ api.multi.tel ہر کلائنٹ IP پتے کو بھی اس ہوسٹ کی تمام درخواستیں ملا کر فی منٹ 300 درخواستوں تک محدود کرتا ہے۔ اس حد پر 429 کے ساتھ شرح کی حد والے ہیڈرز اور JSON خرابی کی بیرونی ساخت کے بجائے سادہ متن کی باڈی واپس آتی ہے۔

درخواستوں کی خرابیاں سنبھالیں

بنیادی ہوسٹ پر ناکامیاں HTTP خرابی کا اسٹیٹس اور JSON واپس کرتی ہیں جس میں status: "error"، code، message اور requestId ہوتے ہیں۔ ہر جواب میں X-Request-ID ہیڈر بھی ہوتا ہے۔ آپ اپنی قدر دے سکتے ہیں؛ 128 حروف سے طویل قدریں کاٹ دی جاتی ہیں۔ مطابقت والا ہوسٹ صرف خرابی کا کوڈ response.code میں واپس کرتا ہے۔ درخواست کی ID، جہاں دستیاب ہو، اور خرابی کا کوڈ لاگ کریں، اور آڈیو، متن اور اسناد لاگز میں نہ رکھیں۔

عام اسٹیٹس:

واپس آنے والے خرابی کے کوڈ پر عمل کریں؛ یہ فرض نہ کریں کہ اِن پٹ کی ہر جانچ کی ناکامی کا ایک ہی اسٹیٹس ہوتا ہے۔

429 یا 503 کے لیے انتظار کریں اور بڑھتے وقفوں اور اسی ارسال کی کلید کے ساتھ دوبارہ کوشش کریں؛ Retry-After موجود ہو تو اس ہیڈر پر عمل کریں۔ غلط اِن پٹ یا اسناد کے لیے پہلے وجہ درست کریں۔ پچھلے ٹاسک قطار میں ہوں تو بار بار نئی کلیدیں نہ بھیجیں۔