वाक् और अनुवाद कार्य

नीचे दिए गए 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 मौजूद हो तो उसका पालन करें। अमान्य इनपुट या क्रेडेंशियल के लिए पहले कारण ठीक करें। पुराने कार्य कतार में हों तो बार-बार नई कुंजियाँ न भेजें।