লেখা অনুবাদের API

এই API লেখা অনুবাদ করে সারিবদ্ধ কাজ হিসেবে, প্রতি কাজে একটি লক্ষ্য ভাষায়। লেখা জমা দিন, ফেরত পাওয়া কাজের ID রেখে দিন এবং প্রক্রিয়াকরণ শেষ হওয়া পর্যন্ত কাজের তথ্য আনুন। প্রতিটি অনুরোধ HTTPS দিয়ে আপনার অ্যাকাউন্টের লগইন তথ্যসহ পাঠান: উদাহরণে দেখানো HTTP Basic লগইন তথ্য বা API টোকেন ব্যবহার করে, যেমন প্রমাণীকরণ অংশে বলা হয়েছে। লগইন তথ্য আপনার সার্ভারেই রাখুন।

এন্ডপয়েন্ট

দুটি API সার্ভার, https://api.multi.tel এবং সামঞ্জস্যের জন্য রাখা সার্ভার https://api.multitel.net, একই অ্যাকাউন্টের আওতাধীন কাজ, আইডেমপোটেন্সি কী, সীমা ও বিলিং ভাগ করে নেয়। প্রতিক্রিয়ার বাইরের কাঠামো আলাদা, তাই উপযুক্ত প্রতিক্রিয়া বিশ্লেষকসহ ধারাবাহিকভাবে একই সার্ভার ব্যবহার করুন।

সার্ভার api.multi.tel-এ প্রতিটি পাথের জন্য এই বিকল্প প্রিফিক্সও ব্যবহার করা যায়: /v1/translate; এটি যে প্রিফিক্সের পরিবর্তে বসবে তা হলো /v3/translate। সার্ভার api.multitel.net-এ ব্যবহার করুন এই পাথগুলি: /v3/translate।

সেবার তথ্যের প্রতিক্রিয়ায় থাকে enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages ও ratesNanosPerCharacter। cpuLanguages প্রচলিত অনুবাদের জন্য গ্রহণযোগ্য মূল ভাষার কোডগুলি তালিকাভুক্ত করে। ratesNanosPerCharacter প্রতিটি ইঞ্জিনের জন্য উৎসের প্রতি কোড পয়েন্টের নির্ধারিত মূল্য দেয়, মার্কিন ডলারের একশো কোটিতম ভাগে: 5000 মানে প্রতি দশ লক্ষ কোড পয়েন্টে $5। প্রতিক্রিয়াটি বর্তমানে উন্নত অনুবাদ পাওয়া যাচ্ছে কি না জানায় না; না পাওয়া গেলে উন্নত অনুবাদের হিসাব চাওয়ার প্রতিক্রিয়ায় 503 আসে। এই তথ্য পড়া বিনামূল্যে।

লেখা অনুবাদ করুন

JSON পাঠান এই হেডারসহ: Content-Type: application/json; গন্তব্য POST https://api.multi.tel/v3/translate। প্রতি কাজের একটি লক্ষ্য ভাষা থাকে, তাই প্রতিটি লক্ষ্য ভাষার জন্য আলাদা কাজ জমা দিন।

লোকেল কোড হলো BCP 47 ট্যাগ, যার মধ্যে 2 থেকে 63 অক্ষর, সংখ্যা ও হাইফেন থাকে। এগুলি মান্য রূপে রূপান্তরিত হয়, তাই en-us নথিভুক্ত হয় এই রূপে: en-US। অবৈধ ট্যাগ এবং und, mul বা zxx দিলে 400 invalid_translation_language ফেরত আসে। প্রচলিত অনুবাদের প্রাপ্যতা মূল ভাষা দিয়ে পরীক্ষা করা হয়, এবং nb ও nn গণনা করা হয় এই ভাষা হিসেবে: no। আঞ্চলিক লক্ষ্য, যেমন fr-CA, গ্রহণ ও নথিভুক্ত করা হয়, তবে প্রচলিত অনুবাদের ফল মূল ভাষা অনুসরণ করে এবং অঞ্চলের ভাষারীতি প্রতিফলিত হওয়ার নিশ্চয়তা নেই।

এই সার্ভারে অনুরোধের বডি 128 KiB-এর মধ্যে রাখুন। লেখা UTF-8 হিসেবে পাঠান, প্রতিটি non-ASCII অক্ষরকে \u সিকোয়েন্স হিসেবে escape না করে, কারণ escape করলে 20,000 অক্ষরের অনুরোধও সীমা ছাড়িয়ে যেতে পারে।

বডিতে শুধু এই চারটি ফিল্ড গ্রহণ করা হয়। অন্য যেকোনো প্রপার্টি দিলে 400 invalid_translation_request দিয়ে প্রত্যাখ্যান করা হয়, যেমন idempotency_key, মালিকের ID, বিনামূল্যে প্রক্রিয়াকরণের ফ্ল্যাগ এবং অংশগুলির অ্যারে।

আইডেমপোটেন্সি ও পুনর্ব্যবহার

প্রতিবার জমা দেওয়ার সময় প্রয়োজন একটি Idempotency-Key হেডার, যার দৈর্ঘ্য 1 থেকে 190 অক্ষর। ASCII অক্ষর, সংখ্যা, -, _, . ও : ব্যবহার করুন, শুরু বা শেষে স্পেস ছাড়া; কী না থাকলে বা 191 বা তার বেশি অক্ষরের হলে 400 দিয়ে প্রত্যাখ্যান করা হয়। কীগুলি আপনার অ্যাকাউন্ট এবং অনুবাদ সেবার আওতায় থাকে, উভয় সার্ভার ও আপনার অ্যাকাউন্টের সব লগইন তথ্য জুড়ে।

• একই কী দিয়ে একই লেখা, মান্য রূপের ভাষা ও ইঞ্জিন পাঠালে বিদ্যমান কাজটি HTTP 200 এবং duplicate: true সহ ফেরত আসে, আর কোনো চার্জ ছাড়া।
• একই কী দিয়ে ভিন্ন লেখা, ভাষা বা ইঞ্জিন পাঠালে 409 idempotency_conflict ফেরত আসে। কাজ তৈরির পরে প্রক্রিয়াকরণ সংস্করণ বদলে গেলেও একই কীতে 409 ফেরত আসে। সেক্ষেত্রে আবার জমা না দিয়ে মূল কাজের ID দিয়ে সেটির তথ্য পড়ুন।
• একই লেখা, মান্য রূপের ভাষা ও ইঞ্জিনের সঙ্গে নতুন কী পাঠালে বিদ্যমান কাজটি HTTP 200 এবং duplicate: true সহ ফেরত আসে, নতুন প্রক্রিয়াকরণ চার্জ ছাড়া, যদি ওই বিষয়বস্তু ও বর্তমান প্রক্রিয়াকরণ সংস্করণের কোনো কাজ সারিতে, চলমান, সম্পূর্ণ বা পেমেন্টের অপেক্ষায় থাকে। পেমেন্টের অপেক্ষায় থাকা পুনর্ব্যবহৃত কাজেরও পেমেন্ট নিষ্পত্তি করতে হয়। ব্যর্থ কাজ পুনর্ব্যবহার করা হয় না: নতুন কাজ তৈরি হয় এবং সম্পূর্ণ হলে চার্জ করা হয়।

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

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: translation-example-001" \
  --data '{"text":"Please move my appointment to Tuesday at 3 PM, not 11 AM.","source_language":"en","target_language":"es","engine":"cpu"}' \
  -o translation-job.json \
  https://api.multi.tel/v3/translate

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

নতুন কাজ HTTP 202 ফেরত দেয়। উদাহরণের লেখায় 57 কোড পয়েন্ট আছে, তাই প্রতি দশ লক্ষ কোড পয়েন্টে $5 হারে খরচ হয় $0.000285। সংক্ষিপ্ত প্রতিক্রিয়া (শনাক্তকারীটি উদাহরণ):

{
  "status": "success",
  "data": {
    "id": "8b2e4c71-5d3a-4f09-a6e2-1c7f9d3b5a28",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "engine": "cpu",
    "sourceLocale": "en",
    "targetLocale": "es",
    "sourceCharacters": 57,
    "costUsd": "0.000285000",
    "costIsEstimate": true,
    "pricePerMillionCharactersUsd": "5.000000000",
    "progress": null
  }
}

জমা দেওয়ার প্রতিক্রিয়ায় আরও আসতে পারে 402 insufficient_balance যখন প্রিপেইড ব্যালান্স দিয়ে অন্য অসমাপ্ত কাজসহ এই কাজের খরচ মেটানো যায় না, এবং 429 translation_queue_full যখন আপনার অ্যাকাউন্ট বা সেবায় অনেক বেশি অসমাপ্ত কাজ থাকে। এই ক্ষেত্রগুলিতে 503 ফেরত আসে:

• paid_translation_not_enabled যখন অর্থপ্রদত্ত অনুবাদ বন্ধ থাকে।
• translation_unavailable উন্নত অনুবাদের অনুরোধে, যখন উন্নত অনুবাদ অনুপলব্ধ থাকে।
• translation_pricing_unavailable যখন নির্বাচিত ইঞ্জিনের কোনো মূল্যহার নির্ধারিত নেই।

429 ও 503 প্রতিক্রিয়ার পরে একই কী দিয়ে পরে চেষ্টা করুন।

অনুবাদের মান বেছে নিন

দীর্ঘ লেখা ছোট অংশে প্রক্রিয়াকরণ করে আবার যুক্ত করা হয়। লাইন ব্রেক ও স্পেস বদলাতে পারে, এবং প্রক্রিয়াকরণের সীমানা পেরিয়ে কোনো বাক্যের প্রসঙ্গ হারিয়ে যেতে পারে। মূল লেখা রেখে দিন এবং যুক্ত করা ফল পর্যালোচনা করুন। প্রচলিত অনুবাদ আঞ্চলিক ট্যাগের মূল ভাষা ব্যবহার করে; ট্যাগ গ্রহণ ও নথিভুক্ত করলেই আঞ্চলিক শব্দচয়নের নিশ্চয়তা হয় না।

প্রচলিত অনুবাদ CPU কর্মীতে চলে। উন্নত অনুবাদ লেখা নির্ধারিত বহিরাগত AI সেবায় পাঠায়। তার ফলও পর্যালোচনা করতে হয়; প্রতিটি ভাষার জোড়া বা লেখার ধরনের জন্য একটি ইঞ্জিন বেশি নির্ভুল হবে, সেবা এমন নিশ্চয়তা দেয় না।

প্রচলিত অনুবাদ একটি খসড়া, যার মান ও প্রক্রিয়াকরণের সময় ভাষার জোড়াভেদে বদলায়। উন্নত অনুবাদ এমন লেখার জন্য যেখানে প্রসঙ্গ গুরুত্বপূর্ণ, তবে গুরুত্বপূর্ণ নাম, সংখ্যা, নেতিবাচক অর্থ ও প্রতিশ্রুতির জন্য সেটিও পর্যালোচনা করতে হয়। কোনো বিকল্পই মূল কথার লিখিত রূপে আগে থেকে থাকা ভুল সংশোধন করে না, তাই তুলনার জন্য মূলটি রেখে দিন।

ব্যবহার করুন GET /v3/translate একই API সার্ভারে, বর্তমান প্রাপ্যতা, সমর্থিত প্রচলিত অনুবাদের ভাষা এবং নির্ধারিত মূল্যহার জানতে। প্রচলিত অনুবাদের অনুরোধে উৎস বা লক্ষ্য মূল ভাষা এই তালিকায় না থাকলে: cpuLanguages, 422 translation_language_pair_unavailable ফেরত আসে। যখন source_language দেওয়া থাকে এবং তার মূল ভাষা লক্ষ্যের মূল ভাষার সমান হয়, অনুরোধে 409 translation_same_language ফেরত আসে, কাজ তৈরি হয় না। উন্নত অনুবাদ আলাদাভাবে চালু করা হয়: অনুপলব্ধ থাকলে উন্নত অনুবাদের কাজ জমা ও হিসাব নেওয়া উভয়েই 503 ফেরত আসে।

আগে খরচের হিসাব নিন

সার্ভার api.multi.tel-এ একই JSON বডি পাঠান এই ঠিকানায়: POST /v3/translate/estimate। আইডেমপোটেন্সি কী লাগে না। হিসাব নেওয়ার সময় 422 ও 409 পরীক্ষাসহ একই যাচাই হয়, কিন্তু কাজ তৈরি, লেখা অনুবাদ, অর্থ সংরক্ষণ, ব্যালান্স পরীক্ষা বা অ্যাকাউন্টে চার্জ করা হয় না। HTTP 200-এর সঙ্গে estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd ও costUsd এই ফিল্ডের মধ্যে থাকে: data। উপরের উদাহরণে costUsd হলো 0.000285000 প্রচলিত মূল্যহারে। উন্নত অনুবাদ অনুপলব্ধ থাকলে উন্নত অনুবাদের হিসাব চাওয়ার প্রতিক্রিয়ায় 503 service_unavailable ফেরত আসে। হিসাবের জন্য বর্তমানে নির্ধারিত মূল্যহার ব্যবহৃত হয়। কাজ তৈরির সময় তার মূল্যহার স্থির হয় এবং সেই হার দিয়ে চার্জ গণনা হয়।

অনুবাদ আনুন

নতুন জমা দেওয়া কাজে HTTP 202 ফেরত আসে, আর বিদ্যমান বা পুনর্ব্যবহৃত কাজে HTTP 200। রেখে দিন data.id এবং ব্যবহার করুন সবার জন্য প্রযোজ্য এই নির্দেশিকা: কাজের প্রবাহ। কাজের অবজেক্টে এই ফিল্ডগুলি থাকে:

• id, status, engine, sourceLocale ও targetLocale।
• sourceCharacters, costUsd, costIsEstimate ও pricePerMillionCharactersUsd।
• progress ও createdAt।
• modelVersion, প্রক্রিয়াকরণ সংস্করণের একটি অস্বচ্ছ স্ট্রিং।
• duplicate পুনর্ব্যবহৃত কাজের প্রতিক্রিয়ায় থাকে।
• failureCode ব্যর্থ কাজের জন্য: translation_failed, translation_timeout, input_failed বা worker_lease_lost।

ব্যর্থ কাজের costUsd শূন্য দেখায়।

সম্পূর্ণ কাজে থাকে data.result, যার মধ্যে থাকে sourceLocale (উৎস ভাষা না দিলে খালি), targetLocale, অনুবাদ করা text (অংশগুলির লেখা লাইন ব্রেক দিয়ে যুক্ত করা), এবং segments। এই API দিয়ে জমা দেওয়া লেখার জন্য segments-এ একটি এন্ট্রি থাকে, যাতে থাকে অনুবাদ করা text এবং লক্ষ্য language। পেমেন্টের অপেক্ষায় থাকা কাজের ফল নিষ্পত্তি না হওয়া পর্যন্ত আটকে রাখা হয়।

api.multitel.net ব্যবহার

সামঞ্জস্যের জন্য রাখা এন্ডপয়েন্ট POST https://api.multitel.net/v3/translate একই JSON ফিল্ড এবং একই Idempotency-Key হেডার গ্রহণ করে। হেডার না থাকলে JSON বডিতে একটি idempotency_key স্ট্রিংও গ্রহণ করে। অন্য যেকোনো অতিরিক্ত ফিল্ড দিলে 400 unsupported_translation_option দিয়ে প্রত্যাখ্যান করা হয়। এই সার্ভারে কাঁচা বডি সর্বোচ্চ 256,000 বাইট হতে পারে এবং 20,000 কোড পয়েন্টের বেশি লেখায় 413 translation_too_large ফেরত আসে, 400-এর পরিবর্তে। খালি source_language বাদ দেওয়া হয়েছে বলে ধরা হয়। 429 প্রতিক্রিয়ায় থাকে Retry-After: 15। এই সার্ভার আরও এই ত্রুটিগুলি ফেরত দেয়:

• 400 json_body_required বডি না থাকলে, অবৈধ JSON বা JSON scalar হলে। একটি JSON অবজেক্ট পাঠান।
• 400 invalid_translation_options যখন text, target_language বা engine অনুপস্থিত, খালি বা স্ট্রিং নয়, অথবা source_language স্ট্রিং নয়।
• 400 invalid_translation_text লেখায় শুধু হোয়াইটস্পেস থাকলে।
• 400 invalid_translation_engine ইঞ্জিন অজানা হলে।
• 400 idempotency_key_required কী অনুপস্থিত, খালি বা অতিরিক্ত দীর্ঘ হলে, অথবা স্ট্রিং নয় এমন idempotency_key।
• 400 invalid_job ভুলভাবে গঠিত কাজের ID-এর জন্য।

এই সার্ভারের অনুবাদ সেবার প্রতিক্রিয়া এই বাইরের কাঠামো ব্যবহার করে: {"status":{"code":HTTP_STATUS},"response":{...}}, যেখানে status একটি অবজেক্ট। কাজের ID পড়ুন response.id থেকে এবং সম্পূর্ণ ফল পড়ুন response.result থেকে। ত্রুটির ক্ষেত্রে কোড থাকে response.code ফিল্ডে, কোনো বার্তা বা অনুরোধের ID ছাড়া। প্রমাণীকরণ ব্যর্থতা (401) সার্ভারের সাধারণ সাইন-ইন পরীক্ষা থেকে ফেরত আসে এবং বডি আলাদা হতে পারে, তাই বিশ্লেষণের আগে HTTP স্ট্যাটাস পরীক্ষা করুন। কাজ প্রধান সার্ভারের সঙ্গে ভাগ করা হয়, তবে কাজের অবস্থা পরীক্ষা, পেমেন্ট নিষ্পত্তি ও ব্যবহার দেখার জন্য একই সার্ভার ব্যবহার করুন, যাতে বিশ্লেষক বাইরের কাঠামোর সঙ্গে মেলে। এই সার্ভার একই JSON ফিল্ড এই পাথেও গ্রহণ করে: /v3/translate/estimate আইডেমপোটেন্সি কী ছাড়া, এবং তার হিসাব থাকে response এর মধ্যে।