पाठ अनुवाद 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 में भेजें। हर गैर-ASCII वर्ण को \u सीक्वेंस में एस्केप करने से 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 स्केलर हो। 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 के अंतर्गत होता है।