परिचय और त्वरित शुरुआत

1. कैपसॉल्वर पायथन एसडीके का परिचय

एसडीके तीन स्वतंत्र पैकेजों के रूप में शिप होता है - प्रत्येक pip install के माध्यम से अपने आप इंस्टॉल किया जा सकता है - साथ ही एक साथी उदाहरण भंडार भी। साथ में वे आपको पायथन की कुछ पंक्तियों में “पेज पर एक कैप्चा है” से “मेरे पास एक वैध टोकन है” तक जाने देते हैं - चाहे आप एक बार की स्क्रिप्ट लिख रहे हों, प्लेराइट के साथ एक वास्तविक ब्राउज़र चला रहे हों, या एक स्वायत्त एआई एजेंट में समाधान क्षमता को जोड़ रहे हों।

यह CapSolver की AI सॉल्विंग सेवा द्वारा संचालित है। एसडीके आपकी तरफ से सब कुछ संभालता है - कैप्चा का पता लगाना, मापदंडों को इकट्ठा करना, सेवा को कॉल करना, और परिणाम को वापस भरना - जबकि वास्तविक पहचान और समाधान क्लाउड में होता है। मूल विचार एक वाक्य में आता है: आपका कोड (या आपका मॉडल) तय करता है कि क्या करना है, और कैपसॉल्वर इसे हल करने का काम संभालता है।

1.1 मुख्य विशेषताएं

✅ एआई-पावर्ड टोकन सॉल्विंग - कैपसॉल्वर एक टोकन लौटाता है जिसे आप लक्ष्य साइट पर सबमिट करते हैं।
✅ दो उपयोग मोड - शुद्ध एपीआई (टोकन मोड, ज्ञात साइट कुंजियों के लिए, ब्राउज़र की आवश्यकता नहीं) और प्लेराइट-आधारित ब्राउज़र मोड।
✅ प्रमुख कैप्चा का कवरेज - रीकैप्चा v2 / v3 (एंटरप्राइज़ सहित) और क्लाउडफ्लेयर टर्नस्टाइल।
✅ पूरी तरह से एसिंक एपीआई - async / await पर निर्मित, आधुनिक क्रॉलर और एजेंटों के लिए एक प्राकृतिक फिट।
✅ तीन स्तरित पैकेज - निम्न-स्तरीय इंजन से लेकर एजेंट टूल्स से लेकर एमसीपी सेवा तक; आपको जो चाहिए उसे चुनें (1.2 देखें)।
✅ बंडल किए गए सीएलआई - capsolver , capsolver-agent , और capsolver-mcp आपको बिना कोई कोड लिखे डायग्नोस्टिक्स चलाने देते हैं।

1.2 समर्थित कैप्चा और पैरामीटर

SDK वर्तमान में निम्नलिखित कैप्चा प्रकारों को हल करता है:

प्रकार	एनम (`CaptchaType`)	टूल वैल्यू (`captcha_type`)	नोट्स
रीकैप्चा v2	`RECAPTCHA_V2`	`reCaptchaV2`	अदृश्य शामिल है
रीकैप्चा v3	`RECAPTCHA_V3`	`reCaptchaV3`	उद्यम शामिल है
क्लाउडफ्लेयर टर्नस्टाइल	(बादल भड़कना)	`cloudflare`	टर्नस्टाइल विजेट

प्रत्येक प्रकार के लिए आवश्यक मुख्य पैरामीटर website_url + website_key हैं। reCAPTCHA v3 अतिरिक्त रूप से page_action , min_score और एक enterprise संकेत ले सकता है, जबकि Cloudflare cdata ले सकता है। आप किसी भी समय अपने वर्तमान निर्माण द्वारा समर्थित प्रकारों का निरीक्षण कर सकते हैं:

cap = create_capsolver(api_key="YOUR_API_KEY")
print(cap.get_supported_captchas())

ध्यान दें: ब्राउज़र मोड में आपको इन मापदंडों को हाथ से प्रदान करने की आवश्यकता नहीं है - get_captcha_info(page) आपके लिए लाइव पेज से सीधे प्रकार और साइट कुंजी को पढ़ता है।

2. मुख्य क्षमताएं (एसडीके)

2.1 तीन पैकेज

पूर्ण सुविधा सेट और एक उदाहरण भंडार। इनमें से चुनने के लिए ये तीन सहकर्मी नहीं हैं - बाद वाले दोनों capsolver-core के शीर्ष पर बनाए गए हैं, जो बस एक अलग इंटरफ़ेस के माध्यम से समान समाधान क्षमता प्रदान करते हैं। वह चुनें जो आपके काम करने के तरीके से सबसे अच्छी तरह मेल खाता हो।

** capsolver-core - कोर एसडीके (इंजन)**

निम्नतम-स्तरीय पैकेज और साझा इंजन पर अन्य दो निर्भर हैं। यह कैप्चा को हल करने को चार चरणों में विभाजित करता है - पता लगाएं → पैरामीटर पढ़ें → हल करें → वापस भरें - और ग्रैन्युलैरिटी के दो स्तर प्रदान करता है: जब साइट कुंजी ज्ञात हो, तो शुद्ध एपीआई (टोकन मोड, कोई ब्राउज़र नहीं) पर जाएं; जब आपके पास केवल पृष्ठ हो, तो Playwright को स्वतः पता लगाने दें और परिणाम वापस भरें। प्लग करने योग्य हैंडलर रजिस्ट्री के साथ पूरी तरह से एसिंक।

इसके लिए सर्वोत्तम: स्क्रिप्ट, क्रॉलर और स्वचालन जहां आप कोड को नियंत्रित करते हैं और एलएलएम की आवश्यकता नहीं होती है।
प्रवेश बिंदु: create_capsolver() → solve() / solve_on_page()।
इंस्टॉल करें: pip install capsolver-core (ब्राउज़र मोड के लिए [playwright] जोड़ें)।

** capsolver-agent - एजेंट उपकरण**

कोर को ऐसे टूल्स के रूप में लपेटता है जिन्हें एलएलएम कॉल कर सकता है: यह फ्रेमवर्क-अज्ञेयवादी टूल स्कीमा और एक एसिंक निष्पादक, साथ ही तैयार लैंगचेन BaseTool कार्यान्वयन प्रदान करता है। अपने लूप के भीतर, मॉडल “सॉल्व” को उसी तरह कॉल करता है जैसे वह “क्लिक” या “टाइप” कहता है, और निष्पादक उस कॉल को कोर के तरीकों से रिले करता है और एक संरचित परिणाम देता है।

इसके लिए सर्वोत्तम: मॉडल को निर्णय लेने दें कि कब हल करना है - ओपनएआई फ़ंक्शन कॉलिंग, ओपनएआई एजेंट एसडीके, लैंगचेन, ब्राउज़र उपयोग, या कोई कस्टम एजेंट लूप।
प्रवेश बिंदु: get_all_tools() + create_executor() , या get_langchain_tools() ।
इंस्टॉल करें: pip install capsolver-agent (लैंगचेन के लिए [langchain] जोड़ें)।

** capsolver-mcp - एमसीपी सेवा**

मॉडल कॉन्टेक्स्ट प्रोटोकॉल के माध्यम से उपकरणों के समान सेट को एक मानक सेवा के रूप में प्रदर्शित करता है। कोई भी एमसीपी-संगत क्लाइंट कनेक्शन पर इन उपकरणों को स्वचालित रूप से खोजता है - प्रति-क्लाइंट एडाप्टर कोड की आवश्यकता नहीं है। तीन ट्रांसपोर्ट का समर्थन करता है: stdio, SSE, और स्ट्रीमेबल-http।

इसके लिए सर्वश्रेष्ठ: एआई क्लाइंट के अंदर प्लग-एंड-प्ले उपयोग - क्लाउड डेस्कटॉप, क्लाउड कोड, कर्सर, विंडसर्फ, क्लाइन और बहुत कुछ, लगभग शून्य एकीकरण कोड के साथ।
प्रवेश बिंदु: capsolver-mcp कमांड, या create_server()।
इंस्टॉल करें: pip install capsolver-mcp (ब्राउज़र टूल के लिए [browser] जोड़ें)।

भण्डार	पैकेज	एक पंक्ति की भूमिका
कैप्सोल्वर-कोर	`capsolver-core`	कोर एसडीके - कैप्चा का पता लगाएं, समाधान करने के लिए एपीआई को कॉल करें, टोकन वापस भरें
एजेंट-कैप्सोल्वर	`capsolver-agent`	एजेंट उपकरण - फ्रेमवर्क-अज्ञेयवादी उपकरण स्कीमा + लैंगचेन उपकरण
एमसीपी-कैप्सोल्वर	`capsolver-mcp`	एमसीपी सेवा - मॉडल कॉन्टेक्स्ट प्रोटोकॉल के माध्यम से समाधान टूल को उजागर करें

2.2 उपयोग के मामले

जब भी कोई कैप्चा अगले चरण को अवरुद्ध करता है, तो यह एसडीके अपना स्थान अर्जित कर लेता है। कुछ विशिष्ट परिदृश्य:

वेब स्क्रैपिंग/डेटा संग्रह

एक क्रॉलर एक लिस्टिंग पेज, सर्च पेज, या लॉगिन वॉल पर रीकैप्चा या टर्नस्टाइल को हिट करता है, और संपूर्ण संग्रह पाइपलाइन रुक जाती है। टोकन प्राप्त करने और इसे अपने अनुरोध के साथ सबमिट करने के लिए टोकन मोड का उपयोग करें, या इसे सीधे पृष्ठ में भरने के लिए ब्राउज़र मोड का उपयोग करें - किसी भी तरह से, स्क्रैपिंग जारी रहती है। → अनुशंसित: capsolver-core (साइट कुंजी ज्ञात होने पर टोकन मोड; गतिशील पृष्ठों के लिए solve_on_page)।

खाता एवं कार्यप्रवाह स्वचालन

साइन-अप, लॉगिन, पासवर्ड रीसेट और चेकआउट जैसे बहु-चरण प्रवाह अक्सर एक विशिष्ट चरण पर कैप्चा फेंक देते हैं, जिससे पूरी स्क्रिप्ट रुक जाती है। समाधान को ठीक उसी चरण में छोड़ें - एक बार टोकन भर जाने के बाद, स्क्रिप्ट फ़ॉर्म सबमिट करना जारी रखती है, रीडायरेक्ट की प्रतीक्षा करती है, और शेष चरणों को पूरा करने के लिए चलाती है। → अनुशंसित: capsolver-core ब्राउज़र मोड; विशेष रूप से सहज जब आपकी स्क्रिप्ट पहले से ही नाटककार को प्रेरित करती है।

एआई एजेंट (स्वायत्त ब्राउज़िंग)

किसी एजेंट को “लॉग इन करें और ऑर्डर खींचें” जैसा कार्य दें और यह बिना किसी चेतावनी के रास्ते में कहीं कैप्चा हिट कर देगा। मॉडल को स्वयं क्लिक करने के बजाय - पिक्सेल-परिपूर्ण लक्ष्यीकरण और मानव-जैसे कर्सर पथ नकली पिछले जोखिम इंजनों के लिए कठिन हैं, और छवि-पुनः प्रयास लूप संदर्भ विंडो में बाढ़ लाते हैं - इसके लिए एक “समाधान” कार्रवाई दर्ज करें: जब यह कैप्चा को हिट करता है, तो यह कार्रवाई को कॉल करता है, एक टोकन वापस प्राप्त करता है, और प्रवाह को तोड़ने के बिना उसी ब्राउज़र सत्र में जारी रहता है। → अनुशंसित: capsolver-agent (मॉडल को इसे स्वयं कॉल करने दें), या capsolver-mcp (इसे सीधे AI क्लाइंट के अंदर उपयोग करें)।

स्वचालित परीक्षण/आंतरिक उपकरण

एंड-टू-एंड परीक्षणों और आंतरिक संचालन उपकरणों को मैन्युअल हस्तक्षेप के बिना, आपकी अपनी या तीसरे पक्ष की साइटों पर कैप्चा चरणों को विश्वसनीय रूप से साफ़ करने की आवश्यकता होती है, जिससे चीजें धीमी हो जाती हैं। → अनुशंसित: पर्यावरण के अनुसार चुनें - capsolver-core (कोड में) या capsolver-mcp (क्लाइंट में)।

संक्षेप में: जहां भी आपको पायथन में प्रोग्रामेटिक रूप से कैप्चा साफ़ करने की आवश्यकता होती है, यह एसडीके सीमा में है।

3. इंस्टालेशन और एपीआई कुंजी सेटअप

शुरू करने से पहले, एक बात ध्यान में रखें: वास्तविक समाधान कैपसॉल्वर की क्लाउड सेवा पर होता है - एसडीके इसे केवल आपकी ओर से कॉल करता है। तो पहला कदम पैकेज स्थापित करना नहीं है; इसमें एक खाता और एक एपीआई कुंजी है। सेटअप तीन चरणों में है, क्रम में: पंजीकरण करें और एक कुंजी प्राप्त करें → एसडीके स्थापित करें → कुंजी कनेक्ट करें।

3.1 रजिस्टर करें और अपनी एपीआई कुंजी प्राप्त करें

कैपसॉल्वर वेबसाइट पर एक खाता पंजीकृत करें।
डैशबोर्ड खोलें और अपनी एपीआई कुंजी कॉपी करें।
अपने खाते में धनराशि जोड़ें - प्रत्येक सफल समाधान में शेष राशि की खपत होती है, और जब शेष राशि शून्य तक पहुंच जाती है तो समाधान विफल हो जाएगा।

3.2 एसडीके स्थापित करें

तीन पैकेज वर्तमान में GitHub पर ओपन सोर्स के रूप में होस्ट किए गए हैं और अभी तक PyPI पर प्रकाशित नहीं हुए हैं, इसलिए उन्हें git के माध्यम से इंस्टॉल करें। capsolver-core इंजन है, और capsolver-agent और capsolver-mcp दोनों इस पर निर्भर हैं - इसलिए कोर हमेशा आवश्यक होता है। जो भी ऊपरी परत आप उपयोग करना चाहते हैं उसे जोड़ें:

# Engine (required; both other packages depend on it)
pip install git+https://github.com/capsolver-ai/capsolver-core.git
 
# Optional: MCP service — exposes the tools to MCP clients
pip install git+https://github.com/capsolver-ai/capsolver-mcp.git
 
# Optional: Agent tools — LLM-callable tool definitions + LangChain tools
pip install git+https://github.com/capsolver-ai/capsolver-agent.git

ब्राउज़र मोड के लिए (वास्तविक पृष्ठ पर कैप्चा का पता लगाना और टोकन को वापस भरना), [playwright] अतिरिक्त जोड़ें और क्रोमियम इंस्टॉल करें:

pip install "capsolver-core[playwright] @ git+https://github.com/capsolver-ai/capsolver-core.git"
playwright install chromium

ध्यान दें: detect और solve_on_page को ब्राउज़र की अतिरिक्त आवश्यकता होती है; टोकन मोड के लिए किसी ब्राउज़र की आवश्यकता नहीं है।

तीन भंडार हैं:

पैकेज	GitHub रिपोजिटरी
`capsolver-core`	https://github.com/capsolver-ai/capsolver-core
`capsolver-agent`	https://github.com/capsolver-ai/capsolver-agent
`capsolver-mcp`	https://github.com/capsolver-ai/capsolver-mcp

आप इंस्टॉल करने से पहले किसी रिपॉजिटरी को स्थानीय रूप से क्लोन भी कर सकते हैं - स्रोत को पढ़ने या अपना स्वयं का विकास करने के लिए उपयोगी:

git clone https://github.com/capsolver-ai/capsolver-core.git
cd capsolver-core
pip install .            # or: pip install -e .  for an editable install

3.3 अपनी एपीआई कुंजी कनेक्ट करें

अंत में, चरण 3.1 से कुंजी एसडीके को सौंपें। डिफ़ॉल्ट रूप से, सभी पैकेज इसे CAPSOLVER_API_KEY पर्यावरण चर से पढ़ते हैं:

# bash / zsh
export CAPSOLVER_API_KEY="your-capsolver-api-key"
 
# PowerShell
$env:CAPSOLVER_API_KEY = "your-capsolver-api-key"
 
# cmd
set CAPSOLVER_API_KEY=your-capsolver-api-key

वैकल्पिक रूप से, पर्यावरण चर को छोड़ें और api_key="..." को सीधे create_capsolver() पर पास करें।

4. आपका पहला समाधान

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

4.1 टोकन मोड (आप साइट कुंजी पहले से ही जानते हैं)

जब आप कैप्चा प्रकार, पेज यूआरएल और साइट कुंजी जानते हैं, तो किसी ब्राउज़र की आवश्यकता नहीं है - पैरामीटर सौंपें, टोकन वापस प्राप्त करें।

import asyncio
from capsolver_core import create_capsolver, CaptchaType, CaptchaInfo
 
async def main():
    cap = create_capsolver(api_key="YOUR_API_KEY")
 
    info = CaptchaInfo(
        type=CaptchaType.RECAPTCHA_V2,
        website_url="https://example.com",
        website_key="6Lc...",
    )
    solution = await cap.solve(info)
    print(solution.token)  # submit as g-recaptcha-response
 
asyncio.run(main())

4.2 ब्राउज़र मोड (एक कॉल, सीधे लाइव पेज पर)

यदि आपके पास केवल एक पृष्ठ है - और आप स्वयं साइट कुंजी की खोज नहीं करना चाहेंगे - तो एसडीके को पृष्ठ पर प्रत्येक कैप्चा का स्वतः पता लगाने दें, उन्हें एक-एक करके हल करें, और टोकन को वापस डीओएम में भरें। बस आपको एक कॉल करनी है, और आपका काम हो जाएगा।

import asyncio
from capsolver_core import create_capsolver
from playwright.async_api import async_playwright
 
async def main():
    cap = create_capsolver(api_key="YOUR_API_KEY")
 
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        page = await browser.new_page()
        await page.goto("https://example.com/login")
 
        results = await cap.solve_on_page(page)
        for r in results:
            print(r.info.type, r.solution.token if r.solution else None, r.filled, r.error)
 
asyncio.run(main())

एआई एजेंटों के लिए CapSolver कोर एसडीके