आर्टिकल से स्पीच (ATS)

पूरे आर्टिकल को नैरेटेड ऑडियो और ट्रांसक्रिप्शन में बदलें, जो आपके कॉलबैक URL पर एसिंक्रोनस रूप से डिलीवर किया जाएगा।

Article to Speech (ATS) एंडपॉइंट किसी आर्टिकल का टेक्स्ट लेता है और एक MP3 नरेशन के साथ-साथ एक सिंक्रोनाइज़्ड ट्रांसक्रिप्शन (.srt) फ़ाइल बनाता है। यह प्रोसेस एसिंक्रोनस रूप से चलता है: रिक्वेस्ट तुरंत 202 Accepted के साथ वापस आ जाती है, और तैयार फ़ाइलें आपके दिए गए callbackURL पर भेज दी जाती हैं। यही वह सर्विस है जो ATS WordPress प्लगइन को चलाती है।

प्रमाणीकरण

Authorization हेडर में अपनी कंपनी की API की (API key) को Bearer टोकन के तौर पर शामिल करें।

Authorization: Bearer your_api_key

अनुरोध का मुख्य भाग

रॉ आर्टिकल टेक्स्ट और रिक्वेस्ट के बारे में बताने वाले postData ऑब्जेक्ट के साथ एक JSON बॉडी भेजें।

postData ऑब्जेक्ट

उदाहरण अनुरोध

curl -X POST "https://api.moknah.io/process-text" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.",
    "postData": {
        "name": "AI is evolving fast",
        "articleId": "post-123",
        "voiceId": "12",
        "callbackURL": "https://your-site.com/wp-json/ats/v1/callback",
        "preprocessType": "0",
        "regenerate": false
    }
  }'

import requests

response = requests.post(
    "https://api.moknah.io/process-text",
    headers={
        "Authorization": "Bearer your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "text": "الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.",
        "postData": {
            "name": "AI is evolving fast",
            "articleId": "post-123",
            "voiceId": "12",
            "callbackURL": "https://your-site.com/wp-json/ats/v1/callback",
            "preprocessType": "0",
            "regenerate": False
        }
    }
)

# 202 Accepted — the audio is delivered to your callbackURL
print(response.status_code, response.text)

const response = await fetch(
    'https://api.moknah.io/process-text',
    {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer your_api_key',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            text: 'الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.',
            postData: {
                name: 'AI is evolving fast',
                articleId: 'post-123',
                voiceId: '12',
                callbackURL: 'https://your-site.com/wp-json/ats/v1/callback',
                preprocessType: '0',
                regenerate: false
            }
        })
    }
);

// 202 Accepted — result arrives at your callbackURL

तत्काल प्रतिक्रिया

अगर अनुरोध स्वीकार कर लिया जाता है, तो एंडपॉइंट तुरंत जवाब देता है:

Processing started. Results will be sent to the callback URL.

कॉलबैक पेलोड

जब जनरेशन पूरा हो जाता है, तो Moknah आपके callbackURL पर इस JSON बॉडी के साथ एक POST रिक्वेस्ट भेजता है:

{
    "articleId": "post-123",
    "response": {
        "audioFile": "https://api-storage.moknah.io/.../******.mp3",
        "srtFile": "https://api-storage.moknah.io/.../******.srt",
        "signature": "<hmac-sha256-hex>"
    }
}

हस्ताक्षर की पुष्टि करना

यह सिग्नेचर articleId|audioFile|srtFile स्ट्रिंग का HMAC-SHA256 (hex) है, जिसे आपकी API की (key) के SHA-256 hex डाइजेस्ट के साथ तैयार किया गया है। इसे अपनी तरफ़ फिर से कैलकुलेट करें और तुलना करके पक्का करें कि कॉलबैक Moknah से आया है और उसमें कोई छेड़छाड़ नहीं की गई है।

import crypto from 'crypto';

const keyHash = crypto.createHash('sha256').update(API_KEY).digest('hex');
const payload = `${articleId}|${audioFile}|${srtFile}`;
const expected = crypto.createHmac('sha256', keyHash).update(payload).digest('hex');

const isValid = expected === signature;

import hashlib, hmac

key_hash = hashlib.sha256(API_KEY.encode()).hexdigest()
payload = f"{article_id}|{audio_file}|{srt_file}"
expected = hmac.new(key_hash.encode(), payload.encode(), hashlib.sha256).hexdigest()

is_valid = hmac.compare_digest(expected, signature)

आइडेंपोटेंसी और रीजेनरेशन

• हर कंपनी के लिए रिक्वेस्ट को articleId के आधार पर पहचाना जाता है। एक नया articleId एक नया जनरेशन शुरू करता है।
• अगर कोई आर्टिकल अभी बन रहा है, तो दोबारा किए गए अनुरोधों को 409 ALREADY_PROCESSING के साथ रिजेक्ट कर दिया जाता है।
• अगर कोई आर्टिकल पहले ही जेनरेट हो चुका है और ’regenerate’ फ़ॉल्स (false) है, तो मौजूदा ऑडियो को दोबारा जेनरेट किए बिना (और बिना दोबारा चार्ज किए) आपके callbackURL पर फिर से भेज दिया जाता है।
• मौजूदा articleId के लिए बिल्कुल नया जनरेशन करने के लिए regenerate को true पर सेट करें।
• अगर पिछली कोशिश नाकाम रही, तो उस articleId के लिए सेव किया गया रिज़ल्ट खाली हो सकता है। बाद में regenerate false के साथ की गई रिक्वेस्ट वही खाली रिज़ल्ट फिर से दे सकती है, इसलिए ठीक करने के लिए regenerate true के साथ दोबारा भेजें (या नया articleId इस्तेमाल करें)।

समवर्तीता और थ्रूपुट

हर आर्टिकल को टेक्स्ट-टू-स्पीच प्रोवाइडर के ज़रिए उसके वाक्यों को एक साथ (पैरेलल) जनरेट करके सुनाया जाता है। यह प्रोवाइडर एक ’कॉन्करेंसी लिमिट’ (एक साथ काम करने की सीमा) लागू करता है जो आपके पूरे अकाउंट पर लागू होती है। एक ही समय में कई आर्टिकल सबमिट करने से यह लिमिट पार हो सकती है, जिससे अलग-अलग वाक्य — और इसलिए पूरे आर्टिकल — फेल हो सकते हैं।

• जब आप कई हिस्सों वाले पेज पर काम कर रहे हों, तो सभी आर्टिकल एक साथ सबमिट करने के बजाय, एक बार में कुछ ही आर्टिकल (लगभग तीन) पर काम करें।
• ’regenerate’ को ’true’ पर सेट करके किसी भी फ़ेल हुए आर्टिकल को फिर से प्रोसेस करें; पहले से बने हुए आर्टिकल कैश (cache) में सेव होते हैं, इसलिए उन्हें दोबारा भेजने की ज़रूरत नहीं है।
• /process-text एंडपॉइंट पर भी हर क्लाइंट के लिए रेट-लिमिट लागू होती है; लिमिट से ज़्यादा रिक्वेस्ट आने पर ’429 Too Many Requests’ का एरर मिलता है, इसलिए अपने सबमिशन के बीच समय का अंतर रखें या उन्हें बैच में भेजें।

बिलिंग

कैरेक्टर की लागत का हिसाब text में मौजूद कैरेक्टर की संख्या को प्रीप्रोसेसिंग फ़ैक्टर (डिफ़ॉल्ट रूप से 1, और जब preprocessType 2 हो तो 2) से गुणा करके लगाया जाता है। क्रेडिट तभी कटते हैं जब असल में जनरेशन का काम होता है। पहले से जनरेट किए गए आर्टिकल को दोबारा पाना मुफ़्त है, और अगर जनरेशन या डिलीवरी फ़ेल हो जाती है, तो कटे हुए क्रेडिट अपने-आप वापस मिल जाते हैं।

गलतियाँ