কথা থেকে লেখা তৈরি ও অনুবাদের কাজ

নিচের উদাহরণে 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 ফেরত আসে, তাই মূল কাজের আইডি রেখে দিন এবং কাজটি সরাসরি পড়ুন।

ব্যালান্স যোগ করার পরে ফলাফল উন্মুক্ত করুন

কাজের অবস্থা 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 হোস্টেড PBX রেকর্ডিংয়ের জন্য), files, audioSeconds, billedSeconds, accruedUsd এবং debitedUsd.
• অনুবাদের রেকর্ড তারিখ, উৎস ও ইঞ্জিন অনুযায়ী সাজানো গোষ্ঠীতে থাকে। এতে থাকে date, source, engine, jobs, sourceCharacters, accruedUsd এবং debitedUsd.

accruedUsd হলো নয় দশমিক ঘরসহ সঠিক খরচ এবং debitedUsd হলো কাটা অর্থ, পাঁচ দশমিক ঘরসহ। প্রতিটি কাজের চার্জ যেদিন নিষ্পত্তি হয়েছে, সেই UTC তারিখে ব্যবহার নথিভুক্ত হয়। তাই সারিতে থাকা, চলমান, ব্যর্থ ও পেমেন্টের অপেক্ষায় থাকা কাজ দেখা যায় না।

সীমা

প্রতিটি অ্যাকাউন্টে কথা থেকে লেখা তৈরি ও অনুবাদের মোট সর্বোচ্চ 50টি অসমাপ্ত কাজ থাকতে পারে: সারিতে, চলমান বা পেমেন্টের অপেক্ষায়, হোস্টেড PBX রেকর্ডিং প্রক্রিয়াকরণসহ। এই সীমা বা পরিষেবার সামগ্রিক ধারণক্ষমতা পূর্ণ হলে কাজ পাঠালে 429 এবং transcription_queue_full বা translation_queue_full ফেরত আসে। সার্ভার api.multi.tel প্রতিটি ক্লায়েন্ট IP ঠিকানায় প্রতি মিনিটে 300 অনুরোধের সীমাও আরোপ করে; ওই সার্ভারে পাঠানো সব অনুরোধ মিলিয়ে এই সীমা। সীমা অতিক্রম করলে JSON ত্রুটির বাইরের কাঠামোর বদলে রেট-লিমিট হেডার ও সাধারণ পাঠ্য বডিসহ 429 ফেরত আসে।

অনুরোধের ত্রুটি সামলান

প্রধান সার্ভারে ব্যর্থতার ক্ষেত্রে HTTP ত্রুটি স্ট্যাটাস এবং JSON ফেরত আসে, যাতে থাকে status: "error", code, message ও requestId। প্রতিটি প্রতিক্রিয়ায় আরও থাকে X-Request-ID হেডার। আপনি নিজস্ব মান দিতে পারেন; 128 অক্ষরের বেশি হলে মান কেটে ছোট করা হয়। সামঞ্জস্য সার্ভার শুধু ত্রুটির কোড ফেরত দেয় response.code ক্ষেত্রে। অনুরোধের আইডি উপলব্ধ থাকলে সেটি এবং ত্রুটির কোড লগে লিখুন, তবে অডিও, লেখা ও লগইন তথ্য লগে লিখবেন না।

সাধারণ স্ট্যাটাস:

ইনপুট যাচাইয়ের প্রতিটি ব্যর্থতার একই স্ট্যাটাস হয় ধরে না নিয়ে ফেরত পাওয়া ত্রুটির কোড অনুযায়ী কাজ করুন।

429 বা 503 হলে অপেক্ষা করে একই পাঠানোর কী দিয়ে আবার চেষ্টা করুন এবং অপেক্ষার সময় বাড়াতে থাকুন; Retry-After হেডার থাকলে তা মেনে চলুন। অবৈধ ইনপুট বা লগইন তথ্য হলে আগে কারণ ঠিক করুন। আগের কাজগুলি সারিতে থাকা অবস্থায় বারবার নতুন কী পাঠাবেন না।