वाक्-से-पाठ API

यह API पूरी ऑडियो फ़ाइलों का लिप्यंतरण कतारबद्ध जॉब के रूप में करता है। फ़ाइल भेजें, मिला हुआ जॉब ID सहेजें और प्रोसेसिंग पूरी होने तक जॉब की जानकारी प्राप्त करते रहें। हर अनुरोध HTTPS पर अपने खाते के क्रेडेंशियल के साथ भेजें। उदाहरणों में दिखाए गए HTTP Basic क्रेडेंशियल या API टोकन का उपयोग करें, जैसा कि यहाँ बताया गया है: प्रमाणीकरण। क्रेडेंशियल अपने सर्वर पर रखें।

एंडपॉइंट

दो API होस्ट, https://api.multi.tel और संगतता होस्ट https://api.multitel.net, खाते के दायरे वाले एक ही जॉब, इडेम्पोटेंसी कुंजियाँ, सीमाएँ और बिलिंग साझा करते हैं। इनकी अपलोड एन्कोडिंग और रिस्पॉन्स एनवेलप अलग हैं, इसलिए मेल खाते पार्सर के साथ एक ही होस्ट का लगातार उपयोग करें।

होस्ट api.multi.tel पर हर पाथ में प्रीफ़िक्स /v1/speech-to-text का उपयोग /v3/speech_to_text की जगह भी कर सकते हैं, जैसे POST /v1/speech-to-text/estimate। होस्ट api.multitel.net पर /v3/speech_to_text वाले पाथ का उपयोग करें।

सेवा की जानकारी वाला रिस्पॉन्स ये फ़ील्ड देता है: mode (batch), realtime (false), paidEnabled (क्या अभी नए सशुल्क सबमिशन स्वीकार किए जाते हैं), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) और maxUploadBytes (26214400), साथ में एक छोटा description। इसे प्राप्त करना मुफ़्त है और सशुल्क सबमिशन बंद होने पर भी उपलब्ध रहता है; केवल पूरी सेवा अनुपलब्ध होने पर 503 transcription_unavailable मिलता है।

ऑडियो फ़ाइल तैयार करें

अधिकतम 25 MiB (26,214,400 बाइट) और अधिकतम 2 घंटे (7,200 सेकंड) की पूरी ऑडियो फ़ाइल लें। सबमिशन के समय फ़ाइल को ऑडियो स्ट्रीम वाली MP3, WAV, Ogg, FLAC, MOV या Matroska मीडिया फ़ाइल के रूप में पहचाना जाना चाहिए। उसके मेटाडेटा में अवधि शून्य से अधिक और 7,200 सेकंड से ज़्यादा नहीं होनी चाहिए। पहचानी गई फ़ाइल इन जाँचों में विफल हो तो उसे 422 unsupported_audio के साथ अस्वीकार किया जाता है। ऐसी फ़ाइल जिसे इनमें से किसी फ़ॉर्मैट में पढ़ा नहीं जा सकता, अभी इसके बजाय सर्वर त्रुटि (500) के साथ अस्वीकार हो सकती है; ऐसी फ़ाइल बिना बदलाव फिर से न भेजें। केवल फ़ाइल एक्सटेंशन से संगतता तय नहीं होती।

इन जाँचों में सफल होने से यह गारंटी नहीं मिलती कि ऑडियो डिकोड हो सकेगा। ऑडियो एक या दो चैनल में प्रोसेस किया जाता है। दो से अधिक ऑडियो चैनल वाली फ़ाइल, डिकोड होने के बाद 2 घंटे से लंबा ऑडियो, या प्रोसेसिंग के दौरान डिकोड न हो सकने वाली कोई भी अन्य फ़ाइल अंत में failed जॉब बनती है, जिसमें आम तौर पर decode_failed होता है, और शुल्क नहीं लगता। सबमिट करने से पहले मल्टीचैनल ऑडियो को मोनो या स्टीरियो में बदलें।

वैकल्पिक भाषा संकेत बोली गई भाषा का दो या तीन छोटे अक्षरों वाला कोड है, जैसे en। संकेत नहीं देना हो तो फ़ील्ड छोड़ दें; api.multi.tel खाली स्ट्रिंग अस्वीकार करता है। यह संकेत प्रोसेसिंग में मदद करता है, लेकिन समर्थित भाषाओं की सूची से इसकी जाँच नहीं होती, इसलिए बोली गई भाषा का मान्य कोड दें।

लिप्यंतरण जॉब सबमिट करें

JSON को Content-Type: application/json हेडर के साथ POST https://api.multi.tel/v3/speech_to_text पर भेजें। अनुरोध का बॉडी अधिकतम 35 MiB हो सकता है, जिसमें base64 एन्कोडिंग के बाद अधिकतम आकार की फ़ाइल आ जाती है; इससे बड़ा बॉडी 413 के साथ अस्वीकार होता है।

कोई भी अन्य JSON प्रॉपर्टी, जिसमें idempotency_key भी शामिल है, 400 invalid_transcription_request के साथ अस्वीकार होती है। कुंजी को हेडर के रूप में भेजें।

इडेम्पोटेंसी कुंजी

हर सबमिशन के लिए Idempotency-Key हेडर ज़रूरी है, जिसकी लंबाई 1 से 190 वर्ण हो। ASCII अक्षर, अंक, -, _, . और : का उपयोग करें, शुरुआत या अंत में स्पेस न हो: संगतता होस्ट आगे-पीछे का व्हाइटस्पेस हटा देता है और कुंजी को बाइट में मापता है, इसलिए अन्य वर्ण दोनों होस्ट पर अलग-अलग गिने जा सकते हैं। कुंजी न होने पर, या 191 या अधिक वर्णों की कुंजी होने पर, अनुरोध 400 के साथ अस्वीकार होता है।

कुंजियों का दायरा आपके खाते और वाक्-से-पाठ सेवा तक है; यह दोनों होस्ट और खाते के सभी क्रेडेंशियल पर लागू होता है। उसी कुंजी से वही फ़ाइल और भाषा फिर भेजने पर मौजूदा जॉब HTTP 200 और duplicate: true के साथ मिलता है। उसकी स्थिति कुछ भी हो और जॉब बनने के बाद प्रोसेसिंग अपडेट हुई हो, तब भी दोबारा शुल्क नहीं लगता। वही कुंजी अलग फ़ाइल या भाषा के साथ उपयोग करने पर 409 idempotency_conflict मिलता है। नई कुंजी से समान फ़ाइल के लिए भी नया जॉब बनता है, जिसकी प्रोसेसिंग सफलतापूर्वक पूरी होने पर अलग शुल्क लगता है।

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

node -e 'process.stdout.write(JSON.stringify({audioBase64:require("node:fs").readFileSync("completed-call.mp3").toString("base64"),language:"en"}))' > completed-call.json

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: speech-call-001" \
  --data-binary @completed-call.json \
  -o speech-job.json \
  https://api.multi.tel/v3/speech_to_text

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

नया जॉब नीचे दिखाए फ़ील्ड के साथ HTTP 202 देता है और दोबारा वही अनुरोध भेजने पर HTTP 200 के साथ पूरा जॉब ऑब्जेक्ट मिलता है, जिसका वर्णन यहाँ है: लिप्यंतरण पढ़ें। जॉब ID एक UUID है; इसे data.id से पढ़ें। नए जॉब का रिस्पॉन्स ऐसा होता है (पहचानकर्ता और मान उदाहरण हैं):

{
  "status": "success",
  "data": {
    "id": "3f6c1b2e-8a4d-4e7f-9c21-5b0d7e4a9f13",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "source": "api",
    "durationSeconds": 90.5,
    "billedSeconds": 91,
    "costUsd": "0.007583334",
    "pricePerMinuteUsd": "0.005"
  }
}

जॉब कतार में या चालू होने के दौरान durationSeconds, billedSeconds और costUsd फ़ाइल के मेटाडेटा से प्राप्त अनुमान होते हैं। अंतिम शुल्क डिकोड की गई अवधि पर आधारित होता है।

सबमिशन पर 402 insufficient_balance भी मिल सकता है, जब प्रीपेड बैलेंस इस जॉब और आपके बाकी लंबित जॉब की लागत के लिए अपर्याप्त हो; 429 transcription_queue_full जब आपके खाते या सेवा में बहुत ज़्यादा लंबित जॉब हों; 429 audio_validation_busy जब फ़ाइल सत्यापन की क्षमता पूरी तरह व्यस्त हो; और 503 paid_transcription_not_enabled जब सशुल्क लिप्यंतरण बंद हो। 429 और 503 रिस्पॉन्स पर बाद में उसी कुंजी से फिर कोशिश करें।

जॉब बनाए बिना अनुमान पाएँ

वही JSON बॉडी POST https://api.multi.tel/v3/speech_to_text/estimate पर भेजें। इडेम्पोटेंसी कुंजी ज़रूरी नहीं है। अनुमान फ़ाइल का सत्यापन और मापन करता है, लेकिन न लिप्यंतरण करता है, न जॉब बनाता है, न धन आरक्षित करता है, न बैलेंस जाँचता है और न खाते से शुल्क लेता है। language संकेत स्वीकार होता है, लेकिन अनुमान पर असर नहीं डालता।

सफल अनुमान HTTP 200 देता है और ये फ़ील्ड लौटाता है: estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd और costUsd, जो data के अंतर्गत होते हैं। इसमें फ़ाइल के मेटाडेटा की अवधि उपयोग होती है, जबकि पूरे हुए जॉब का शुल्क डिकोड की गई अवधि पर लगता है, जो अलग हो सकती है। अनुमान में भी सबमिशन जैसी फ़ाइल जाँचें होती हैं। अनुमान केवल सशुल्क लिप्यंतरण चालू होने पर उपलब्ध होते हैं (अन्यथा 503 paid_transcription_not_enabled)। फ़ाइल सत्यापन की क्षमता व्यस्त होने पर 429 audio_validation_busy मिल सकता है; थोड़ी देर बाद फिर कोशिश करें।

लिप्यंतरण पढ़ें

पोल करें: GET /v3/speech_to_text/JOB_ID। तरीका यहाँ दिया गया है: जॉब वर्कफ़्लो गाइड। जॉब ऑब्जेक्ट में ये फ़ील्ड होते हैं:

लिप्यंतरण और उसके टाइमस्टैम्प, भाषा लेबल तथा चैनल लेबल अपने-आप बनते हैं और उनकी सटीकता की गारंटी नहीं है। किसी भी गुणवत्ता फ़्लैग को रिज़ल्ट की समीक्षा करने का कारण मानें और महत्वपूर्ण नाम, संख्याएँ तथा प्रतिबद्धताएँ मूल ऑडियो से मिलाएँ। लंबे मौन और बहुत धीमी आवाज़ वाले हिस्से छोड़ दिए जाते हैं और उनके खंड नहीं बनते। रिज़ल्ट अलग-अलग वक्ताओं की पहचान नहीं करता। जब रिज़ल्ट में channelCount का मान 2 हो, तो हर खंड में channel का मान A (पहला, या बायाँ, चैनल) या B (दूसरा, या दायाँ, चैनल) होता है। इससे वक्ता तभी अलग होते हैं जब हर वक्ता अलग चैनल पर रिकॉर्ड हुआ हो। दो-चैनल ऑडियो का शुल्क उसकी बीती अवधि पर एक बार लगता है, प्रति चैनल नहीं। मोनो रिज़ल्ट में चैनल लेबल नहीं होते।

api.multitel.net का उपयोग

संगतता एंडपॉइंट POST https://api.multitel.net/v3/speech_to_text पर multipart/form-data स्वीकार किया जाता है, जिसमें audio फ़ाइल पार्ट और वैकल्पिक language फ़ील्ड होता है; JSON audioBase64 नहीं। खाली language मान को बिना संकेत के माना जाता है। वही Idempotency-Key हेडर भेजें। हेडर न होने पर यह होस्ट idempotency_key फ़ॉर्म फ़ील्ड भी स्वीकार करता है। जिन फ़ील्ड के नाम source, free, billing_source, realtime या stream हों, वे 400 unsupported_transcription_option के साथ अस्वीकार होते हैं; अन्य फ़ॉर्म फ़ील्ड अनदेखे किए जाते हैं। यह होस्ट ये त्रुटियाँ भी लौटाता है:

• 400 idempotency_key_required कुंजी न होने या बहुत लंबी होने पर।
• 400 audio_upload_required अपलोड न होने या पूरी तरह प्राप्त न होने पर।
• 400 invalid_language अमान्य भाषा के लिए।
• 413 invalid_audio_size खाली या बहुत बड़ी फ़ाइल के लिए।
• 400 invalid_job गलत फ़ॉर्मैट वाले जॉब ID के लिए।

इस होस्ट की वाक्-से-पाठ सेवा के रिस्पॉन्स में यह एनवेलप होता है: {"status":{"code":HTTP_STATUS},"response":{...}}। ध्यान दें कि status ऑब्जेक्ट है, स्ट्रिंग नहीं। सफल होने पर response में वही ऑब्जेक्ट होता है जो प्राथमिक होस्ट पर data में होता है, इसलिए जॉब ID response.id है। त्रुटि होने पर response.code में त्रुटि कोड होता है; संदेश या अनुरोध ID नहीं होता। प्रमाणीकरण विफलता (401) होस्ट की सामान्य साइन-इन जाँच से आती है और उसका बॉडी अलग हो सकता है, इसलिए पार्स करने से पहले HTTP स्टेटस जाँचें। होस्ट के बीच अपलोड एन्कोडिंग या रिस्पॉन्स पार्सर की अदला-बदली न करें।

इस होस्ट पर अनुमान के लिए वही multipart फ़ील्ड /v3/speech_to_text/estimate पर POST करें। इडेम्पोटेंसी कुंजी ज़रूरी नहीं है और अनुमान response के अंतर्गत होता है।

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

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Idempotency-Key: speech-call-001" \
  -F "audio=@completed-call.mp3" -F "language=en" \
  -o speech-job.json \
  https://api.multitel.net/v3/speech_to_text

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