Python में CapSkip SDK से hCaptcha: एक call, एक token

Python में CapSkip SDK से hCaptcha हल करने के लिए widget के sitekey और पेज के पते के साथ solver.hcaptcha() call करें, फिर लौटे हुए token और SDK के बताए User-Agent के साथ अपना फ़ॉर्म post करें। SDK टास्क सबमिट करता है, नतीजे के लिए poll करता है और दोनों मान लौटा देता है, इसलिए script में ज़्यादातर retry के नियम और form post ही हैं। इसके पीछे का CapSkip hCaptcha सॉल्वर आपके अपने Windows PC पर, फिक्स्ड कीमत वाले लाइसेंस के साथ चलता है, इसलिए expire हो चुके या ठुकराए गए token को बदलने में कुछ खर्च नहीं होता।

आपको क्या चाहिए

• CapSkip 4.0.0 या बाद का, जो किसी Windows PC पर चल रहा हो। उस रिलीज़ में (3 नवंबर 2026) hCaptcha हल करने की सुविधा जुड़ी, Enterprise समेत। इसे इंस्टॉल करने के लिए देखें: सेटअप गाइड.
• Python 3.10 या बाद का, जो capskip पैकेज का घोषित न्यूनतम वर्ज़न है, और दो पैकेज: capskip 1.6.0 या बाद का, जिसमें पहली बार hCaptcha method आया, और requests। टेस्ट capskip 1.6.0 और requests 2.34.2 के साथ Python 3.11.7 और 3.14.0 पर हुआ, किसी और वर्ज़न पर नहीं।
• एक PowerShell prompt, जहाँ आप pip install capskip requests चलाते हैं।
• hCaptcha widget वाला ऐसा पेज जो आपका अपना हो या जिसे ऑटोमेट करने की आपको अनुमति हो, और उसका sitekey। sitekey कहाँ मिलता है, यह चरण 2 में दिखाया गया है।
• CapSkip के लिए एक पता। मोड इससे तय होता है कि script कहाँ चलती है। Local mode (127.0.0.1) सिर्फ़ उसी PC को सर्व करता है जिस पर CapSkip चल रहा है। Server mode आपके नेटवर्क या पब्लिक IP पर भी सुनता है, इसलिए कोई दूसरा PC, Windows VPS या hosted platform वही रिक्वेस्ट भेज सकता है। मोड आप यहाँ बदलते हैं: कनेक्शन सेटिंग्स। नीचे का कोड डिफ़ॉल्ट CapSkip फ़ॉर्मैट की उम्मीद करता है, इसलिए किसी भी Service Emulator सेटिंग को उसके डिफ़ॉल्ट पर ही रहने दें।
• वैकल्पिक: एक proxy। वह कहाँ जाता है, यह चरण 2 में बताया गया है।

यह कैसे टेस्ट किया गया: दो mock सर्वर के सामने, जो मैंने खुद लिखे थे (यानी टेस्ट के लिए बनाए नकली सर्वर), असली CapSkip app या किसी असली hCaptcha साइट के सामने नहीं। उनमें से एक उन जाँचों की नक़ल करता है जो CapSkip के API दस्तावेज़ के hCaptcha सेक्शन में सूचीबद्ध हैं। दूसरा एक sign-up फ़ॉर्म की भूमिका निभाता है और forward proxy का भी काम करता है। यहाँ कुछ भी असली हल का समय नहीं नापता, और mock में साइट के नियम (एक बार इस्तेमाल होने वाला token, मेल खाता User-Agent, दो मिनट की वैधता) CapSkip के दस्तावेज़ों से आते हैं, hCaptcha से नहीं। असली जाँच वही साइट करती है जिसे आप निशाना बनाते हैं। यह कैसे होता है, इसके लिए यह देखें: hCaptcha के डेवलपर दस्तावेज़.

चरण 1: solver बनाएँ

नीचे के चार कोड ब्लॉक एक ही फ़ाइल में, इसी क्रम में रखें। उसका नाम hcaptcha_demo.py रखें। आख़िरी ब्लॉक के आने तक कुछ नहीं चलता। इन रन में SDK असली capskip 1.6.0 था, और उसके पीछे सिर्फ़ CapSkip app mock था। constructor का apiKey argument डिफ़ॉल्ट रूप से string capskip लेता है, जो तब तक काम करता है जब तक API Key Validation बंद है। अगर आपने validation चालू किया है, तो अपनी key apiKey के रूप में दें।

constructor यह भी तय करता है कि SDK hCaptcha के लिए कितना इंतज़ार करे। उसका recaptchaTimeout argument, डिफ़ॉल्ट रूप से 300 सेकंड, इसलिए लागू होता है क्योंकि widget असली ब्राउज़र में पास किया जाता है। कोड इसे घटाकर 180 सेकंड कर देता है, जो मेरा चुनाव है, CapSkip की सेटिंग नहीं। वह सीमा सिर्फ़ polling पर लगती है। SDK अपनी HTTP calls पर कोई timeout नहीं लगाता, और mock के सामने 20 सेकंड रोका गया जवाब, recaptchaTimeout 5 होने पर भी, call को पूरे 20 सेकंड इंतज़ार में रखे रहा। समस्याएँ exceptions के रूप में आती हैं जिन्हें आप capskip से import करते हैं: ValidationException जब SDK भेजने से पहले ही आपके arguments ठुकरा दे, ApiException जब CapSkip error code दे, TimeoutException जब इंतज़ार खत्म हो जाए और NetworkException जब CapSkip तक पहुँचा न जा सके।

# pip install capskip requests
import re

import requests
from capskip import ApiException, CapSkip

PAGE_URL = "https://example.com/signup"  # the page that shows the widget
SITEKEY = "YOUR_SITEKEY"  # the data-sitekey of its h-captcha div

# Local mode. In Server mode, use your server's address as the host.
# With API Key Validation on, also pass apiKey="YOUR_API_KEY".
solver = CapSkip(host="127.0.0.1", port=8080, recaptchaTimeout=180)

चरण 2: CapSkip से token माँगें

sitekey सार्वजनिक होता है और हर विज़िटर के लिए वही रहता है। ज़्यादातर पेज उसे widget के container पर data-sitekey के रूप में छापते हैं। जो पेज widget को script से बनाता है, वह उसे hcaptcha.render() के sitekey option में देता है, और hCaptcha iframe के पते में वह sitekey= के रूप में दिखता है। उसे SITEKEY में रखें, और जिस पेज पर widget दिखता है उसका पूरा पता PAGE_URL में रखें।

call solver.hcaptcha(SITEKEY, PAGE_URL) है। यह टास्क सबमिट करता है और token तैयार होने तक poll करता है, इसलिए आपके पास कोई task ID नहीं रहता और कोई loop नहीं लिखना पड़ता। raw API के दस्तावेज़ पहले 10 सेकंड रुकने की सलाह देते हैं, लेकिन SDK तुरंत poll करता है, फिर 0.25 सेकंड सोता है और हर बार जब जवाब आता है कि नतीजा अभी तैयार नहीं है, तो उसे दोगुना करता है, ज़्यादा से ज़्यादा 5 सेकंड तक। दस्तावेज़ों के अनुसार एक हल में आम तौर पर 10 से 30 सेकंड लगते हैं। मैंने कभी किसी असली हल का समय नहीं नापा।

नतीजा एक dictionary है। उसके token और code फ़ील्ड में एक ही string होती है, वही जो h-captcha-response के लिए है, और userAgent वह User-Agent है जिसके साथ वह token मिला। respKey फ़ील्ड एक दूसरा मान है जो hCaptcha widget को देता है। वह हमेशा मौजूद रहता है, और जब कुछ न हो तो खाली रहता है, और दस्तावेज़ कहते हैं कि ज़्यादातर साइटें उसे कभी नहीं पढ़तीं, इसलिए कोड उसे अनदेखा करता है। हर नतीजा एक बार ही दिया जाता है और SDK उसे आपके लिए पढ़ लेता है, इसलिए function token और User-Agent दोनों साथ लौटाती है। दस्तावेज़ कहते हैं कि CapSkip userAgent argument का इस्तेमाल तभी करता है जब वह उस ब्राउज़र से मेल खाता हो जिससे वह हल करता है, इसलिए उदाहरण में चुनाव CapSkip पर छोड़ा गया है।

इस method के लिए proxy वैकल्पिक है। दस्तावेज़ कहते हैं कि टेस्ट के लिए एक ही पता काफ़ी है, और एक ही IP से लगातार हल आते रहना वही चीज़ है जिसे पकड़ने के लिए hCaptcha की rate limits बनी हैं। ज़्यादा मात्रा के लिए hCaptcha की सेटिंग्स में proxy की list लोड करें या हर टास्क के साथ proxy भेजें। टास्क पर दिया गया proxy list पर भारी पड़ता है। function proxy को पूरे URL के रूप में लेती है, जैसे http://user:[email protected]:8080, और scheme को proxytype के रूप में तथा बाकी हिस्से को proxy फ़ील्ड के रूप में भेजती है। HTTP और HTTPS proxy जैसे हैं वैसे काम करते हैं। SOCKS proxy के लिए पहले pip install requests[socks] चलाएँ। अगर आप proxies को बदलते (rotate) रहते हैं, तो proxy rotation गाइड में इसका तरीका बताया गया है।

def solve(proxy=None):
    options = {}
    if proxy:  # for example http://user:[email protected]:8080
        scheme, address = proxy.split("://", 1)
        # The SDK sends type as proxytype and uri as proxy.
        options["proxy"] = {"type": scheme.upper(), "uri": address}
    result = solver.hcaptcha(SITEKEY, PAGE_URL, **options)
    return result["token"], result["userAgent"]  # delivered once: keep both

चरण 3: उसी User-Agent के साथ फ़ॉर्म post करें

ब्राउज़र में widget token को h-captcha-response नाम के एक छिपे textarea में लिखता है, और g-recaptcha-response नाम की उसकी एक प्रति भी। ब्राउज़र के बिना आप h-captcha-response खुद भेजते हैं, और अगर फ़ॉर्म में g-recaptcha-response भी है तो उसे भी। नीचे का कोड दोनों भेजता है। आपके फ़ॉर्म के अपने फ़ील्ड भी उनके साथ जाते हैं, और उनके नाम वही होते हैं जो साइट इस्तेमाल करती है। post PAGE_URL पर जाता है, इसलिए अगर फ़ॉर्म का action किसी और पते की ओर इशारा करता है, तो post call का पहला argument, PAGE_URL, बदल दें।

User-Agent मायने रखता है। जवाब उस ब्राउज़र का नाम बताता है जिसने token कमाया, और दस्तावेज़ कहते हैं कि फ़ॉर्म उसी string के साथ सबमिट करें। इसलिए function उसे पेज लोड होने से पहले session पर सेट कर देती है, ताकि पेज लोड और post, दोनों में वही User-Agent जाए। token एक ही बार चलते हैं और जारी होने के करीब दो मिनट बाद expire हो जाते हैं, इसलिए तुरंत post करें और हर कोशिश पर नया token माँगें।

form post में वह पेज भी Referer के रूप में दिया जाता है जहाँ से वह आया है, क्योंकि requests अपने आप न Referer भेजता है न Origin header। कुछ frameworks ऐसे HTTPS form post को ठुकरा देते हैं जिसमें दोनों में से कुछ नहीं होता। इसका एक उदाहरण Django CSRF दस्तावेज़ है, जिसमें Origin header के बिना आने वाले HTTPS रिक्वेस्ट के लिए सख़्त referer जाँच बताई गई है।

def submit_form(session, token, user_agent, email):
    # Every request from here on carries the User-Agent the token was
    # earned with, the page load included.
    session.headers["User-Agent"] = user_agent
    session.get(PAGE_URL, timeout=30)  # picks up the page's own cookies
    return session.post(
        PAGE_URL,
        data={
            "email": email,  # your form's own fields go here
            "h-captcha-response": token,
            "g-recaptcha-response": token,  # the widget fills both
        },
        headers={"Referer": PAGE_URL},  # requests sends no Referer by itself
        timeout=30,
    )

चरण 4: retry के नियमों के साथ पूरा उदाहरण

आख़िरी ब्लॉक सभी चरणों को एक script में जोड़ता है। इसे hcaptcha_demo.py के अंत में जोड़ें, देखें कि ऊपर के PAGE_URL और SITEKEY आपके अपने हैं, और जिस फ़ोल्डर में फ़ाइल है वहाँ से python hcaptcha_demo.py चलाएँ (अगर python आपके PATH में नहीं है तो py hcaptcha_demo.py चलता है)। script ज़्यादा से ज़्यादा तीन कोशिशें करती है।

किस error code पर दोबारा कोशिश होगी, यह code तय करता है। दस्तावेज़ कहते हैं कि ERROR_CAPTCHA_UNSOLVABLE का मतलब है कि टास्क नाकाम हुआ और नया टास्क सबमिट करना चाहिए, इसलिए retry के सेट में सिर्फ़ यही code है। दो और नाकामियाँ अपना कारण खुद बताती हैं, क्योंकि दोबारा भेजने पर भी वही नतीजा होगा: ऐसा sitekey जिसे hCaptcha ने उस पेज के लिए ठुकरा दिया, और ऐसा proxy जिस तक पहुँचा नहीं जा सकता। Common errors तालिका के बाकी codes request या setup की ओर इशारा करते हैं। SDK code को ApiException के संदेश के अंदर रखता है, सादे text के रूप में या एक छोटे JSON envelope में, इसलिए error_code ERROR_ वाला शब्द निकाल लेता है और दोनों के साथ काम करता है। बाकी सब कुछ script को तुरंत रोक देता है, उन तीन exceptions समेत जिन्हें loop नहीं पकड़ता: ValidationException, TimeoutException और NetworkException।

जिस फ़ॉर्म को साइट ठुकरा दे, उसके लिए नया token और एक और कोशिश मिलती है। अगर तीन token एक ही तरह से नाकाम हों, तो फ़ॉर्म के फ़ील्ड देखें। किसी छूटे फ़ील्ड पर HTTP 400 आता रहता है, token चाहे कितना भी अच्छा हो। साथ ही, reply.ok का मतलब सिर्फ़ इतना है कि status 400 से नीचे था। कई साइटें 200 देती हैं और पेज में error संदेश दिखाती हैं, इसलिए उस जाँच की जगह ऐसी चीज़ की जाँच रखें जिसे आपकी साइट सिर्फ़ सफलता पर दिखाती है।

# Only a task CapSkip could not solve gets another try. A bad sitekey, a
# dead proxy or a wrong key would fail the same way again.
RETRY = {"ERROR_CAPTCHA_UNSOLVABLE"}


def error_code(err):
    # The message holds the code as bare text or inside a JSON envelope.
    found = re.search(r"ERROR_[A-Z_]+", str(err))
    return found.group(0) if found else str(err)


def sign_up(email, proxy=None):
    session = requests.Session()
    if proxy:
        session.proxies = {"http": proxy, "https": proxy}
    for attempt in range(1, 4):
        try:
            token, user_agent = solve(proxy)
        except ApiException as err:
            code = error_code(err)
            if code not in RETRY:
                raise
            print(f"attempt {attempt}: {code}, new task")
            continue
        reply = submit_form(session, token, user_agent, email)
        if reply.ok:
            return reply
        print(f"attempt {attempt}: the site answered {reply.status_code}, new token")
    raise RuntimeError("no accepted form after 3 attempts")


if __name__ == "__main__":
    reply = sign_up("[email protected]")
    print(reply.status_code, reply.text[:60])

mock रन में script ने इस तरह व्यवहार किया, और Python 3.11.7 तथा 3.14.0 पर नतीजे एक जैसे थे:

साइट वाली पंक्तियों को मेरे अपने mock के टेस्ट मानें। उसके नियम CapSkip के दस्तावेज़ों का पालन करते हैं, सिवाय इसके कि मैंने एक session cookie की जाँच जोड़ी और यह शर्त कि दोनों token फ़ील्ड मेल खाएँ। ये hCaptcha या किसी असली साइट के बारे में कुछ साबित नहीं करते।

आम errors

अगर साइट फिर भी token को ठुकराए

कुछ साइटें, खासकर hCaptcha Enterprise वाली, ऐसे token ठुकरा देती हैं जिन्हें hCaptcha ने जोखिम भरा आँका, भले ही widget पास हो गया हो। CapSkip के दस्तावेज़ इन्हें सख़्त sitekeys कहते हैं। दस्तावेज़ hCaptcha के लिए High score mode सुझाते हैं, जो Settings, Captcha types, hCaptcha में है। इसके लिए CapSkip चलाने वाले PC पर Google Chrome इंस्टॉल होना चाहिए। 4.0.0 का changelog कहता है कि यह मोड डिफ़ॉल्ट रूप से चालू है, और जब यह बंद हो या Chrome न हो, तो hCaptcha CapSkip के Custom Browser में हल होता है। दस्तावेज़ एक अच्छा proxy भी माँगते हैं, और यह भी कि फ़ॉर्म उसी पते से, जवाब वाले User-Agent के तहत सबमिट हो। असली सख़्त साइट के बिना मैं इनमें से कुछ भी टेस्ट नहीं कर सका, इसलिए इसे CapSkip के दस्तावेज़ों का मार्गदर्शन मानें, ऐसा कुछ नहीं जिसे मैंने खुद जाँचा हो।

अपनी script से किसी server पर CapSkip इस्तेमाल करना

script को CapSkip से बस एक host और एक port चाहिए। Server mode में CapSkip आपके नेटवर्क के दूसरे डिवाइस से, या Windows VPS पर इंटरनेट से भी कनेक्शन स्वीकार करता है, और सेटअप गाइड स्थिर पब्लिक IP की सलाह देता है। Server mode के लिए CapSkip का administrator के रूप में चलना ज़रूरी है। सर्वर का पता और port CapSkip() को दें, और script में बाकी कुछ नहीं बदलता। मालिकाना और बिलिंग भी नहीं बदलते: मशीन आपकी है और कुछ भी मीटर नहीं होता। इससे port दूसरे पतों के लिए खुला रहता है, इसलिए जिन पर आपको भरोसा नहीं, उनके लिए Windows Firewall में block rule बनाएँ।

हल अब server पर होता है। सख़्त sitekey के लिए दस्तावेज़ दोनों तरफ़ एक ही पता माँगते हैं, इसलिए sign_up के proxy argument को एक proxy दें, और वह टास्क तथा आपके session, दोनों को जाएगा।

FAQ

संक्षेप में

Python में hCaptcha हल करना एक hcaptcha() call और उस User-Agent के साथ एक form post पर आकर टिकता है जिसके साथ token मिला। retry तभी करें जब CapSkip टास्क हल न कर पाया हो, और बाकी हर error पर script को रुकने दें। क्योंकि CapSkip एक लोकल captcha सॉल्वर है, इसलिए ठुकराए गए token को दोबारा आज़माना बस loop को फिर से चलाने की बात है। दूसरे प्रकारों के SDK calls के लिए Python कैप्चा सॉल्वर पेज देखें। widget को पास होते हुए देखना हो, तो आप यह डेमो खोल सकते हैं: hCaptcha डेमो.