Kling का API आपसे असल में क्या माँगता है

Chapter 1

छह मॉडल, एक लॉगिन, और कोई स्पष्ट सही उत्तर नहीं

एक डेवलपर पहली बार Kling के डॉक्युमेंटेशन पेज पर लॉगिन करता है और बाईं तरफ़ की सूची में एक के बाद एक नाम दिखते हैं – Kling 3.0 Turbo, Kling 3.0 और 3.0 Omni, Kling O1, Kling 2.6, Kling 2.5 Turbo, फिर Motion Control, Avatar, Audio Generation, और इनके अलावा अलग से Image मॉडल की एक पूरी लिस्ट। किसी एक 'सही' मॉडल का नाम कहीं बड़े अक्षरों में नहीं लिखा है।

फ़र्क सिर्फ नाम का नहीं, बनावट का भी है। Kling 3.0 Turbo और उसके साथ लॉन्च हुए नए मॉडल एक नए, सरल API ढांचे पर बने हैं – जिसमें contents नाम की एक अरे होती है जो prompt, image, video जैसे अलग-अलग टुकड़ों को एक साथ रखती है, और टास्क को बैच में या cursor की मदद से खोजा जा सकता है। पुराने मॉडल (kling-v1 से लेकर kling-v2-6 तक) अब भी legacy एंडपॉइंट पर चलते हैं, जहाँ हर पैरामीटर सीधे रिक्वेस्ट बॉडी में अलग-अलग भेजा जाता है।

अच्छी खबर यह है कि दोनों साथ-साथ काम करते रहते हैं। दस्तावेज़ों में साफ़ लिखा है कि legacy API को फ़िलहाल बंद करने की कोई योजना नहीं है, और model_name पैरामीटर पुराने model पैरामीटर के साथ backward compatible है। यानी मौजूदा इंटीग्रेशन को अचानक तोड़ने का डर नहीं है।

फिर भी चुनाव करना पड़ता है, क्योंकि हर मॉडल की क्षमता अलग है। Motion Control सिर्फ किसी रेफरेंस वीडियो की हरकत कॉपी करने के लिए है। Omni मॉडल एक साथ कई इमेज, वीडियो और एलिमेंट को मिलाकर एक जटिल सीन बना सकता है। Kling O1 सबसे नया, सबसे लचीला विकल्प है जो <<<>>> सिंटैक्स से कई तरह की सामग्री को एक प्रॉम्प्ट में जोड़ता है।

इस किताब का बाकी हिस्सा उसी क्रम में चलता है जिस क्रम में एक असली इंटीग्रेशन बनता है – पहले रिक्वेस्ट की बुनियादी बनावट, फिर कैरेक्टर और मोशन जैसे एडवांस फीचर, फिर नतीजा पाना और उसकी लागत समझना, और आख़िर में प्रोडक्शन में जाने से पहले की चेकलिस्ट।

What you can actually do here

नीचे दी गई हर पंक्ति Kling के API दस्तावेज़ों से सीधे ली गई है – कोई अनुमान नहीं। हर पंक्ति के साथ वह चैप्टर लिखा है जहाँ पूरी प्रक्रिया मिलेगी।

पहला रिक्वेस्ट बनाना

कैरेक्टर, मोशन और आवाज़

नतीजा पाना और उसका हिसाब रखना

Chapter 2

रिक्वेस्ट में असल में क्या होना चाहिए

एक डेवलपर पहला रिक्वेस्ट भेजता है और उसे तुरंत 400 एरर मिलता है – अक्सर वजह कोई बड़ी गलती नहीं होती, बल्कि इमेज का साइज़ या aspect ratio होता है जो किसी को याद नहीं रहता।

नए API ढांचे में हर रिक्वेस्ट एक contents अरे से शुरू होती है। इसके हर टुकड़े का एक type होता है – prompt, image (या first_frame/last_frame), video, या element – और हर टुकड़े की अपनी शर्तें हैं। टेक्स्ट प्रॉम्प्ट की एक सीमा है जो मॉडल के हिसाब से 2500 से 3072 अक्षर तक जाती है। इमेज सिर्फ़ .jpg, .jpeg या .png में स्वीकार होती है, उसका साइज़ ज़्यादातर मॉडलों में 50MB से कम होना चाहिए, और उसकी चौड़ाई-ऊँचाई कम से कम 300px और aspect ratio 1:2.5 से 2.5:1 के बीच होनी चाहिए। इससे बाहर जाते ही रिक्वेस्ट अस्वीकार हो जाती है।

settings ऑब्जेक्ट में resolution और duration जैसी आउटपुट सेटिंग्स आती हैं। ज़्यादातर मॉडलों में डिफ़ॉल्ट रिज़ॉल्यूशन 720p है, और 1080p या उससे ऊपर के लिए इसे साफ़ तौर पर सेट करना पड़ता है। duration की अनुमत वैल्यू भी हर मॉडल में अलग-अलग एनम के रूप में तय है, कोई मनचाहा नंबर नहीं चलता।

options ऑब्जेक्ट वह जगह है जहाँ callback_url, external_task_id और watermark_info जैसी चीज़ें आती हैं। external_task_id अपना खुद का ट्रैकिंग नंबर देने का तरीका है – यह सिस्टम के बनाए हुए task ID की जगह नहीं लेता, बल्कि उसके साथ-साथ रहता है, और एक ही अकाउंट के भीतर यूनीक होना ज़रूरी है।

इन सब शर्तों को याद रखने का सबसे आसान तरीका यह है कि हर नए मॉडल के लिए डॉक्युमेंटेशन पेज पर दिया गया curl उदाहरण पहले जस का तस चलाकर देखा जाए, और उसके बाद ही अपने असली डेटा से बदला जाए – क्योंकि दस्तावेज़ों में मौजूद उदाहरण हमेशा वैध सीमाओं के भीतर ही लिखे गए हैं।

Chapter 3

एक शॉट को दूसरे से अलग बताना

एक मार्केटिंग वीडियो में तीन अलग शॉट चाहिए होते हैं – पहले प्रोडक्ट का क्लोज़-अप, फिर इस्तेमाल का सीन, फिर लोगो के साथ खत्म। एक ही प्रॉम्प्ट में यह तीनों चीज़ें अलग-अलग समय पर कैसे कहें?

Kling के ज़्यादातर नए मॉडल multi-shot फ़ॉर्मैट को सपोर्ट करते हैं। प्रॉम्प्ट के भीतर ही 'shot n, m, words;' जैसा एक ढांचा लिखा जा सकता है, जहाँ n शॉट का क्रम नंबर है, m सेकंड में उस शॉट की अवधि है, और words उस शॉट का विवरण है। ज़्यादा से ज़्यादा छह शॉट तक सपोर्ट मिलता है, और सबका जोड़ पूरे वीडियो की कुल अवधि के बराबर होना चाहिए – एक सेकंड कम या ज़्यादा होने पर रिक्वेस्ट में गड़बड़ी आ सकती है।

कुछ मॉडलों (जैसे Kling O1 का Omni वर्ज़न) में एक अलग तरीका भी है – multi_prompt नाम की एक अरे, जहाँ हर शॉट को index, prompt और duration के तीन अलग फ़ील्ड में लिखा जाता है। यह तब उपयोगी है जब शॉट की जानकारी किसी दूसरे सिस्टम से प्रोग्रामेटिक तरीके से आ रही हो, क्योंकि टेक्स्ट पार्स करने के बजाय सीधे स्ट्रक्चर्ड डेटा भेजा जा सकता है।

shot_type नाम का एक पैरामीटर यह तय करता है कि शॉट खुद तय होंगे (customize) या मॉडल खुद बुद्धिमानी से बांटेगा (intelligence)। जब multi_shot को true किया जाता है, तब prompt पैरामीटर बेकार हो जाता है और उसकी जगह multi_prompt या पूरा टेम्प्लेटेड प्रॉम्प्ट काम में आता है – दोनों को एक साथ भेजना गड़बड़ी पैदा कर सकता है।

व्यावहारिक तौर पर, कम शॉट के साथ शुरुआत करना समझदारी है। दो या तीन शॉट का जोड़ जाँचना आसान है; छह शॉट की अवधि का गणित एक सेकंड भी गड़बड़ होने पर पूरा टास्क रिजेक्ट कर सकता है।

Chapter 4

एक चेहरा जो नहीं बदलता

एक ही किरदार को दस अलग-अलग वीडियो में एक जैसा दिखाना – यही वह समस्या है जो ज़्यादातर AI वीडियो टूल हल नहीं कर पाते। हर नई जनरेशन में चेहरा थोड़ा बदल जाता है, और एक सीरीज़ बनाने वाले के लिए यह सबसे बड़ी रुकावट बन जाती है।

Kling का हल Element Library है। पहले Element Management API से एक element_id बनाया जाता है, जिसमें या तो एक वीडियो (जिसे video_character_elements कहा जाता है) या कई इमेज (multi_image_elements) रेफरेंस के तौर पर दी जाती हैं। इसके बाद हर जनरेशन रिक्वेस्ट में सिर्फ़ उस element_id को contents में type:element के तौर पर जोड़ना होता है।

एलिमेंट की संख्या की सीमा जटिल है और मॉडल के हिसाब से बदलती है। जब कोई रेफरेंस वीडियो नहीं है और सिर्फ़ multi-image एलिमेंट हैं, तो रेफरेंस इमेज और एलिमेंट का कुल जोड़ 7 से ज़्यादा नहीं हो सकता। जब रेफरेंस वीडियो मौजूद है, यह सीमा घटकर 4 रह जाती है। Motion Control में एक बार में सिर्फ़ एक ही एलिमेंट स्वीकार होता है।

प्रॉम्प्ट के भीतर एलिमेंट को @नाम के फ़ॉर्मैट से बुलाया जाता है, जैसे @Zhang। दस्तावेज़ इस बारे में एक साफ़ चेतावनी देते हैं – अगर एलिमेंट का नाम प्रॉम्प्ट के किसी और शब्द से मिलता-जुलता है (जैसे प्रॉम्प्ट में किसी का ईमेल पता लिखा हो और एलिमेंट का नाम @gmail हो), तो मॉडल भ्रमित हो सकता है। नाम जितना अनोखा होगा, नतीजा उतना ही भरोसेमंद रहेगा।

जिस डेवलपर को कैरेक्टर कंसिस्टेंसी चाहिए, उसे शुरुआत में ही एक साफ़, पेशेवर रेफरेंस इमेज या वीडियो तैयार करना चाहिए – क्योंकि Element एक बार बन जाने के बाद हर आगे की जनरेशन उसी क्वालिटी पर निर्भर रहती है।

Chapter 5

एक तस्वीर को रेफरेंस जैसा हिलाना

एक डांस वीडियो बनाने वाला चाहता है कि उसकी बनाई हुई इलस्ट्रेशन ठीक वैसे ही हिले जैसे किसी असली इंसान का रेफरेंस वीडियो हिलता है। यही काम Motion Control API के लिए बना है।

यहाँ दो अलग इनपुट भेजने होते हैं – एक image_url, जिसमें वह किरदार है जिसे हिलाना है, और एक video_url, जिसमें वह हरकत है जो कॉपी करनी है। दोनों की अपनी अलग शर्तें हैं: इमेज में किरदार का ऊपरी या पूरा शरीर साफ़ दिखना चाहिए, बहुत उलटी या लेटी हुई पोज़िशन से बचना चाहिए; वीडियो एक ही लगातार शॉट होना चाहिए, बीच में कट या कैमरा मूवमेंट नहीं होना चाहिए, वरना वीडियो को बीच से काट दिया जाएगा।

duration की सीमा character_orientation पर निर्भर करती है – अगर जनरेट हुए वीडियो में किरदार की दिशा वीडियो जैसी रखनी है, तो रेफरेंस वीडियो 30 सेकंड तक लंबा हो सकता है; अगर दिशा इमेज जैसी रखनी है, तो सीमा घटकर 10 सेकंड रह जाती है।

एक बात जो आसानी से नज़रअंदाज़ हो जाती है: अगर हरकत बहुत तेज़ या जटिल है, तो मॉडल सिर्फ़ उतना हिस्सा निकाल पाता है जो वैध ढंग से इस्तेमाल हो सके, और नतीजे में मिलने वाला वीडियो अपलोड किए गए वीडियो से छोटा हो सकता है। दस्तावेज़ साफ़ कहते हैं कि इस स्थिति में खर्च हुए क्रेडिट वापस नहीं मिलते – इसलिए धीमी, स्थिर हरकत वाला रेफरेंस चुनना बेहतर नतीजा और कम जोखिम दोनों देता है।

std और pro दो मोड में से चुनना पड़ता है – std सस्ता और तेज़ है, pro बेहतर क्वालिटी देता है लेकिन ज़्यादा खर्चीला है। जिस काम में क्लाइंट को दिखाना है, वहाँ pro मोड सही चुनाव है; आंतरिक टेस्टिंग के लिए std काफ़ी है।

Chapter 6

वीडियो को आवाज़ देना

एक जनरेट किया हुआ किरदार सिर्फ़ हिलता नहीं, बोलता भी है – और यही वह हिस्सा है जो ज़्यादातर वीडियो टूल अलग से किसी तीसरे टूल से करवाते हैं। Kling इसे अपने ही API में देता है।

settings.audio को native करने पर जनरेट हुए वीडियो में उसकी विज़ुअल हरकत से मेल खाती हुई आवाज़ अपने-आप जुड़ जाती है। जिसे किसी खास आवाज़ में बोलना है, वह प्रॉम्प्ट के भीतर <<<voice_1>>> जैसे फ़ॉर्मैट से उसे पुकार सकता है, और यह क्रम voice_list में दिए गए क्रम से मेल खाना चाहिए। एक टास्क में ज़्यादा से ज़्यादा दो आवाज़ें रेफरेंस की जा सकती हैं।

एक शर्त बार-बार दोहराई गई है और इसे नज़रअंदाज़ करना आसान है: जब audio को native किया जाता है, तब सिर्फ़ 1080p रिज़ॉल्यूशन ही सपोर्ट होता है। अगर resolution 720p पर छोड़ दिया और audio native कर दिया, तो रिक्वेस्ट में टकराव आ सकता है।

अपनी खुद की आवाज़ चाहिए तो Custom Voice API का इस्तेमाल होता है। यहाँ या तो एक साफ़ ऑडियो/वीडियो फ़ाइल (voice_url) दी जाती है, या किसी पुराने जनरेट किए हुए वीडियो का video_id, बशर्ते वह वीडियो V2.6 मॉडल पर audio:on के साथ बना हो, या Avatar/Lip-Sync API से आया हो। आवाज़ का सैंपल 5 से 30 सेकंड के बीच और सिर्फ़ एक इंसान की साफ़ आवाज़ होनी चाहिए – बैकग्राउंड शोर या कई आवाज़ें मिली-जुली होने पर क्लोनिंग की क्वालिटी गिर जाती है।

जिन प्रोडक्ट्स में कई भाषाओं में एक ही किरदार बोलना है, उनके लिए यह पूरा सिस्टम एक तीसरे टूल के बिना, सीधे एक ही API कॉल में हल हो जाता है – बस शर्तों का क्रम याद रखना ज़रूरी है।

Chapter 7

बिना इंतज़ार किए जवाब का इंतज़ार

वीडियो जनरेशन तुरंत नहीं होती – एक टास्क सबमिट होता है, फिर वह processing में जाता है, और कुछ सेकंड से लेकर कुछ मिनट बाद succeeded या failed स्टेटस पर पहुँचता है। सवाल यह है कि इस बीच का इंतज़ार कैसे संभाला जाए।

दो तरीके हैं। पहला, बार-बार GET /tasks को पोल करना और status चेक करते रहना – सीधा तरीका, पर सर्वर पर ग़ैरज़रूरी लोड डालता है। दूसरा, callback_url सेट करना, जिससे जैसे ही टास्क का स्टेटस बदलता है, सर्वर खुद एक notification भेज देता है। ज़्यादातर प्रोडक्शन इंटीग्रेशन के लिए दूसरा तरीका बेहतर है।

callback में जो payload आता है, वह टास्क की id, status, message (फ़ेल होने पर वजह), और outputs की एक लिस्ट लेकर आता है। हर आउटपुट टाइप – वीडियो, इमेज, ऑडियो, वॉइस, एलिमेंट – का अपना अलग structure है, इसलिए यह पहले से तय करना ज़रूरी है कि कोड किस टाइप की उम्मीद कर रहा है।

अगस्त 2026 में एक नया फीचर जुड़ा है – Webhook Signature। यह callback रिक्वेस्ट की पहचान जाँचने का तरीका देता है, यानी यह पक्का करता है कि जो notification मिला है वह असल में Kling के सर्वर से आया है, किसी और से नहीं। इसके साथ एक Test Callback सुविधा भी है जो असली टास्क चलाए बिना कॉन्फ़िगरेशन जाँचने देती है। जो पहले से callback इस्तेमाल कर रहे हैं, उनके लिए यह ज़रूरी नहीं है – मौजूदा इंटीग्रेशन बिना बदलाव के चलता रहता है।

सबसे ज़रूरी बात, जो दस्तावेज़ों में बार-बार दोहराई गई है: outputs में मिली url सुरक्षा कारणों से सिर्फ़ 30 दिन के लिए वैध रहती है, उसके बाद हमेशा के लिए हट जाती है। जिस भी सिस्टम में यह इंटीग्रेशन बन रहा है, वहाँ callback मिलते ही या टास्क सफल होते ही फ़ाइल को अपने स्टोरेज में डाउनलोड कर लेना एक ज़रूरी क़दम है, न कि बाद के लिए टाला जाने वाला काम।

Chapter 8

तीन सौ इफेक्ट्स जिनका कोई लिंक नहीं देता

मुख्य मॉडल पेजों में – Text to Video, Image to Video, Motion Control – कहीं भी सीधा रास्ता नहीं मिलता जो बताए कि 307 तैयार वीडियो इफेक्ट्स भी मौजूद हैं। यह API एक अलग सेक्शन में, Effects के नीचे बैठा है।

POST /v1/videos/effects एक ही एंडपॉइंट है जो effect_scene नाम के पैरामीटर से तय करता है कि कौन सा इफेक्ट लगाना है – एक डांस स्टेप, एक त्योहार वाला फ़िल्टर, एक पालतू जानवर वाला मज़ाकिया इफेक्ट। ज़्यादातर इफेक्ट (292 में से) सिर्फ़ एक इनपुट इमेज माँगते हैं और input ऑब्जेक्ट की बनावट scene के हिसाब से अलग होती है।

यह सूची स्थिर नहीं है। अपडेट लॉग में लगभग हर हफ़्ते नए इफेक्ट जुड़ते दिखते हैं – अगस्त 2026 की शुरुआत में ही तीन अलग तारीखों पर नए इफेक्ट लॉन्च हुए, और साथ ही एक पुराना इफेक्ट (magic_match_tree) बंद कर दिया गया। जो कोड effect_scene की वैल्यू को हार्डकोड करके रखता है, उसे यह मान लेना चाहिए कि सूची बदलती रहेगी।

जिस प्रोडक्ट को त्योहार-आधारित या ट्रेंड-आधारित कंटेंट चाहिए (जैसे नए साल के फ़िल्टर या किसी खेल टूर्नामेंट के थीम), उसके लिए यह पूरी क्षमता एक अलग मॉडल बनाए बिना, सिर्फ़ इसी एक एंडपॉइंट से मिल जाती है – बशर्ते कोई इसे ढूँढ़े।

व्यावहारिक सलाह: effect_scene की पूरी और ताज़ा सूची के लिए दस्तावेज़ों में दिए गए अलग 'Video Effects Center' लिंक को नियमित तौर पर चेक करना, न कि इस किताब या किसी पुराने कोड में लिखी एनम वैल्यू पर भरोसा करना।

Chapter 9

हर जनरेशन की असल कीमत

एक प्रोडक्ट टीम को यूज़र से कितना चार्ज करना है, यह तय करने से पहले यह जानना ज़रूरी है कि हर जनरेशन का असल खर्च क्या है – और यह खर्च रिज़ॉल्यूशन, अवधि और मॉडल के हिसाब से बदलता है।

बिलिंग का पैटर्न आम तौर पर आउटपुट की अवधि पर आधारित है, फ़्लैट रेट पर नहीं। यानी 5 सेकंड का वीडियो और 10 सेकंड का वीडियो अलग-अलग यूनिट खर्च करते हैं, और ज़्यादा रिज़ॉल्यूशन (1080p या 4K) कम रिज़ॉल्यूशन से महँगा पड़ता है। कुछ खास फ़ीचर – जैसे रेफरेंस वीडियो का इस्तेमाल, या किसी खास आवाज़ को टास्क में जोड़ना – बिलिंग को एक अलग, ऊँची कैटेगरी में डाल देते हैं।

इसका हिसाब रखने के लिए दो अलग API हैं, और इन्हें मिलाना नहीं चाहिए – एक resource package deduction देखने के लिए (जो पैकेज खरीदा गया है उससे कितना घटा), और एक balance deduction देखने के लिए (सीधे बैलेंस से कितना कटा)। Deduction Query API समय, API key, पैकेज ID जैसे कई पैमानों पर फ़िल्टर करने देता है, और कई शर्तों को एक साथ (intersection और union दोनों तरह से) जोड़ने देता है।

जिस प्रोडक्ट में यूज़र को पहले से अनुमानित लागत दिखानी है, उसे duration और resolution को पहले से यूज़र से पूछकर टास्क बनाने से पहले ही अंदाज़ा लगाना चाहिए, क्योंकि टास्क फ़ेल होने पर भी कुछ शर्तों में क्रेडिट वापस नहीं मिलता (जैसे Motion Control में हरकत तेज़ होने पर छोटा नतीजा मिलना)।

जो टीम बड़े पैमाने पर, कई यूज़र के लिए यह सेवा चला रही है, उसके लिए Deduction Query API को अपने बिलिंग डैशबोर्ड से जोड़ना शुरुआत से ही समझदारी है – बाद में हर यूज़र के खर्च का हिसाब मैन्युअली जोड़ना व्यावहारिक नहीं रहता।

Chapter 10

प्रोडक्शन में जाने से पहले

डेमो में सब कुछ ठीक चलता है। प्रोडक्शन में जाने से पहले कुछ चीज़ें ऐसी हैं जो डेमो के दौरान नज़र नहीं आतीं, पर लॉन्च के बाद पहली शिकायत बन जाती हैं।

पहला: 30 दिन की समय-सीमा। हर जनरेट हुए नतीजे की url सिर्फ़ 30 दिन के लिए वैध है। अगर सिस्टम इसे अपने स्टोरेज में कॉपी नहीं करता, तो एक महीने बाद पुराने यूज़र का कंटेंट अचानक गायब हो जाएगा – यह एक ऐसी शिकायत है जो सपोर्ट टीम तक तभी पहुँचती है जब यूज़र पहले ही नाराज़ हो चुका होता है।

दूसरा: watermark_info डिफ़ॉल्ट रूप से false है, यानी वॉटरमार्क के बिना नतीजा मिलता है। अगर किसी बिज़नेस मॉडल में मुफ़्त टियर पर वॉटरमार्क ज़रूरी है, तो इसे साफ़ तौर पर true सेट करना होगा – यह अपने-आप नहीं होता।

तीसरा: Terms of API Paid Service और Privacy Policy दोनों साफ़ कहते हैं कि यूज़र का अपलोड किया गया कंटेंट (इमेज, आवाज़, वीडियो) कंटेंट मॉडरेशन और ख़ास फ़ीचर (जैसे चेहरे के फ़ीचर पॉइंट) के लिए प्रोसेस किया जाता है, पर मॉडल ट्रेनिंग के लिए इस्तेमाल करने का वादा साफ़ तौर पर नहीं किया जाता। जो प्रोडक्ट अपने यूज़र को डेटा प्राइवेसी का भरोसा देना चाहता है, उसे यह शर्तें अपनी खुद की प्राइवेसी पॉलिसी में साफ़ तौर पर दोहरानी चाहिए।

चौथा और आख़िरी क़दम, अगर callback_url इस्तेमाल हो रहा है: नया Webhook Signature फीचर चालू करना, ताकि यह पक्का हो कि आने वाला हर notification असल में Kling से है। यह वैकल्पिक है, पर जिस भी सिस्टम में पैसों से जुड़ा टास्क (जैसे बिलिंग अपडेट) callback पर निर्भर है, वहाँ यह पहला दिन से ही चालू करना चाहिए।

इन चार चीज़ों की जाँच – स्टोरेज, वॉटरमार्क, डेटा शर्तें, और सिग्नेचर वेरिफ़िकेशन – लॉन्च से पहले किसी एक दोपहर में पूरी हो सकती है, और यही वह दोपहर है जो लॉन्च के बाद की सबसे बड़ी शिकायतों को रोकती है।

Questions readers actually ask

Contact / More useful information from RamthaMedia

Official source links:
Kling