diff --git a/README.md b/README.md index b7d418b..ec435ad 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # CapMonster Cloud Python SDK: AI Captcha Solver & Anti-Bot Bypass

- + CapMonster Cloud Python SDK

@@ -20,7 +20,7 @@ --- -Official asynchronous Python SDK for [CapMonster Cloud](https://capmonster.cloud/?utm_source=github&utm_medium=readme&utm_campaign=python_repo). Easily plug ultra-fast AI captcha recognition into **Playwright, Selenium, Puppeteer, Scrapy, BeautifulSoup, and Requests** automation workflows without human-in-the-loop delays. +Official asynchronous Python SDK for [CapMonster Cloud](https://capmonster.cloud/en/?utm_source=github&utm_medium=referral&utm_campaign=python_repo_readme). Easily plug ultra-fast AI captcha recognition into **Playwright, Selenium, Puppeteer, Scrapy, BeautifulSoup, and Requests** automation workflows without human-in-the-loop delays. **[👉 Get your Free API Key & Free Trial Balance on CapMonster Cloud](https://dash.capmonster.cloud/Account/SignUp?utm_source=github&utm_medium=referral&utm_campaign=python_repo_readme)** @@ -28,11 +28,11 @@ Official asynchronous Python SDK for [CapMonster Cloud](https://capmonster.cloud ## ⚡ Highlights & Benchmarks -- ⚡ **Sub-Second Speed:** 100% automated neural networks solve captchas in as fast as 0.3–2.5 seconds. -- 🤖 **Zero Human Workers:** Reliable, consistent uptime without mechanical turk latencies. -- 🌐 **Native Automation Wrappers:** Plug-and-play code snippets for **Playwright & Selenium**. -- 🛡️ **Modern Anti-Bot Bypass:** Full support for Cloudflare Turnstile, DataDome, GeeTest v4, Amazon WAF, and Imperva. -- 💰 **Lowest Cost per 1,000 Solutions:** High accuracy rate with competitive pay-as-you-go pricing. +- ⚡ **Sub-Second Speed:** Automated AI models solve captchas in 300 ms to 6 seconds depending on the system load. +- 🤖 **Zero Human Workers:** 100% automated machine learning pipeline with no manual latencies. +- 🌐 **Browser Automation Ready:** Works out-of-the-box with **Playwright, Selenium, and Puppeteer**. +- 🛡️ **Modern Anti-Bot Bypass:** Full support for Cloudflare Turnstile, reCAPTCHA Enterprise, GeeTest, and Amazon WAF. +- 💰 **Cost-Effective:** Low-cost pricing structure based on pay-as-you-go balance. --- @@ -44,27 +44,27 @@ pip install capmonstercloudclient --- -## 🚀 Quick Start Examples +## 🚀 Quick Start & Usage Examples -### 1. Simple Async Example (reCAPTCHA v2 Proxyless) +### 1. Asynchronous reCAPTCHA v2 Solving ```python import asyncio from capmonstercloudclient import CapMonsterClient, ClientOptions from capmonstercloudclient.requests import RecaptchaV2ProxylessRequest -# 1. Initialize client with your API key +# Initialize client with your API key from dashboard options = ClientOptions(api_key="YOUR_CAPMONSTER_API_KEY") client = CapMonsterClient(options=options) async def main(): - # 2. Build the task payload + # Build the task payload request = RecaptchaV2ProxylessRequest( websiteUrl="https://lessons.zennolab.com/captchas/recaptcha/v2_simple.php?level=high", websiteKey="6Lcg7CMUAAAAANphynKgn9YAgA4tQ2KI_iqRyTwd" ) - # 3. Solve captcha and receive token + # Send task and receive token result = await client.solve_captcha(request) print("reCAPTCHA Token:", result.get("gRecaptchaResponse")) @@ -72,7 +72,7 @@ if __name__ == "__main__": asyncio.run(main()) ``` -### 2. Playwright / Selenium Turnstile & reCAPTCHA Integration +### 2. Browser Automation (Playwright + Cloudflare Turnstile) ```python import asyncio @@ -84,7 +84,7 @@ options = ClientOptions(api_key="YOUR_CAPMONSTER_API_KEY") client = CapMonsterClient(options=options) async def run_scraper(): - # Request Turnstile solution + # Solve Turnstile challenge via CapMonster Cloud turnstile_req = TurnstileProxylessRequest( websiteUrl="https://target-website.com/login", websiteKey="0x4AAAAAAABnPIDnK2k_e-2" @@ -92,12 +92,12 @@ async def run_scraper(): solution = await client.solve_captcha(turnstile_req) token = solution.get("token") + # Inject token into Playwright browser session async with async_playwright() as p: browser = await p.chromium.launch(headless=False) page = await browser.new_page() await page.goto("https://target-website.com/login") - # Inject the solved token into the page await page.evaluate(f'document.querySelector("[name=cf-turnstile-response]").value = "{token}";') await page.click("#submit-button") await browser.close() @@ -108,67 +108,69 @@ if __name__ == "__main__": --- -## 🛡️ Supported CAPTCHA Types & Documentation - -| Protection Type | Task Request Class | Proxyless Support | Docs Link | -| :--- | :--- | :---: | :--- | -| **Cloudflare Turnstile** | `TurnstileProxylessRequest` / `TurnstileRequest` | ✅ Yes | [Documentation](https://docs.capmonster.cloud/docs/captchas/turnstile-task) | -| **reCAPTCHA v2** | `RecaptchaV2ProxylessRequest` / `RecaptchaV2Request` | ✅ Yes | [Documentation](https://docs.capmonster.cloud/docs/captchas/recaptcha-v2-task) | -| **reCAPTCHA v3 / Enterprise** | `RecaptchaV3ProxylessRequest` / `RecaptchaV2EnterpriseRequest` | ✅ Yes | [Documentation](https://docs.capmonster.cloud/docs/captchas/recaptcha-v3-task) | -| **GeeTest (v3, v4)** | `GeeTestProxylessRequest` / `GeeTestRequest` | ✅ Yes | [Documentation](https://docs.capmonster.cloud/docs/captchas/geetest-task) | -| **DataDome** | `DataDomeCustomTaskRequest` | 🌐 Proxy Required | [Documentation](https://docs.capmonster.cloud/docs/captchas/datadome) | -| **Amazon WAF** | `AmazonWafRequest` | ✅ Yes | [Documentation](https://docs.capmonster.cloud/docs/captchas/amazon-task) | -| **Imperva / Incapsula** | `ImpervaCustomTaskRequest` / `Proxyless` | ✅ Yes | [Documentation](https://docs.capmonster.cloud/docs/captchas/incapsula) | -| **Binance CAPTCHA** | `BinanceTaskRequest` / `Proxyless` | ✅ Yes | [Documentation](https://docs.capmonster.cloud/docs/captchas/binance) | -| **Standard Image-to-Text** | `ImageToTextRequest` | ✅ Yes | [Documentation](https://docs.capmonster.cloud/docs/captchas/image-to-text) | -| **Complex Image Grid** | `RecaptchaComplexImageTaskRequest` | ✅ Yes | [Documentation](https://docs.capmonster.cloud/docs/captchas/complex-image-task) | +## 🛡️ Supported CAPTCHA Types + +All task types conform to the official [CapMonster Cloud API Documentation](https://docs.capmonster.cloud/docs/captchas/?utm_source=github&utm_medium=referral&utm_campaign=python_repo_readme): + +| Protection Type | Task Request Class | Proxyless Mode | +| :--- | :--- | :---: | +| **Cloudflare Turnstile** | `TurnstileProxylessRequest` / `TurnstileRequest` | ✅ Supported | +| **reCAPTCHA v2** | `RecaptchaV2ProxylessRequest` / `RecaptchaV2Request` | ✅ Supported | +| **reCAPTCHA v3** | `RecaptchaV3ProxylessRequest` | ✅ Supported | +| **reCAPTCHA Enterprise** | `RecaptchaV2EnterpriseProxylessRequest` / `RecaptchaV2EnterpriseRequest` | ✅ Supported | +| **GeeTest (v3, v4)** | `GeeTestProxylessRequest` / `GeeTestRequest` | ✅ Supported | +| **Amazon WAF** | `AmazonWafRequest` | ✅ Supported | +| **DataDome** | `DataDomeCustomTaskRequest` | 🌐 Proxy Required | +| **Imperva / Incapsula** | `ImpervaCustomTaskRequest` / `ImpervaCustomTaskProxylessRequest` | ✅ Supported | +| **Binance CAPTCHA** | `BinanceTaskRequest` / `BinanceTaskProxylessRequest` | ✅ Supported | +| **Standard Text CAPTCHA** | `ImageToTextRequest` | ✅ Supported | +| **Complex Image Tasks** | `RecaptchaComplexImageTaskRequest` | ✅ Supported | --- -## 🛠️ Architecture & Pipeline Flow +## 🛠️ How It Works ```text -[ Scraping Script (Python / Playwright) ] - │ - ▼ - [ Extract sitekey & website URL ] - │ - ▼ - [ 🤖 CapMonsterClient SDK ] ──► POST task to CapMonster Cloud API - │ - ▼ - [ Instant Neural Network Solve ] ──► Async token retrieval (< 1s) - │ - ▼ -[ Inject Token into Form & Submit ] ──► Bypass complete! +[ Script / Scraper ] + │ + ▼ +[ Extract sitekey & website URL ] + │ + ▼ +[ CapMonsterClient API ] ──► POST createTask to https://api.capmonster.cloud + │ + ▼ +[ Neural Network Processing ] ──► Poll getTaskResult (300ms - 6s) + │ + ▼ +[ Receive Token & Autosubmit ] ──► Complete bypass ``` --- -## ⚙️ Best Practices & Troubleshooting +## ⚙️ Best Practices -- **Token Expiration:** Most tokens (reCAPTCHA, Turnstile) are valid for 120 seconds. Inject and submit the token immediately after solving. -- **Proxy Matching:** For high-security targets (DataDome, Cloudflare Strict), use the same residential proxy in both the scraping session and the CapMonster request task. -- **Account Balance:** Make sure your balance is positive. You can monitor and top up credits directly in your [Dashboard](https://dash.capmonster.cloud/?utm_source=github&utm_medium=readme&utm_campaign=python_repo). +- **Token Expiration:** Most tokens (reCAPTCHA, Turnstile) remain valid for 120 seconds. Inject and submit the solution immediately after receiving the response. +- **Proxy Usage:** For custom tasks and strict protections, use the same proxy in your scraping session and the CapMonster task payload. +- **Balance Monitoring:** Ensure your account balance remains positive in the [Dashboard](https://dash.capmonster.cloud/?utm_source=github&utm_medium=referral&utm_campaign=python_repo_readme). --- -## 📚 Resources & Community +## 📚 Official Documentation & Links -- 📖 [Official CapMonster Cloud Documentation](https://docs.capmonster.cloud/) -- 🎯 [Full Captcha API Specifications](https://docs.capmonster.cloud/docs/captchas/) -- 💬 [Support & Developer Community](https://capmonster.cloud/en/?utm_source=github&utm_medium=readme&utm_campaign=python_repo#support) +- 📖 [Getting Started Guide](https://docs.capmonster.cloud/docs/getting-start/?utm_source=github&utm_medium=referral&utm_campaign=python_repo_readme) +- 🎯 [Supported Captchas Overview](https://docs.capmonster.cloud/docs/captchas/?utm_source=github&utm_medium=referral&utm_campaign=python_repo_readme) +- ⚙️ [API Methods Reference](https://docs.capmonster.cloud/docs/methods/?utm_source=github&utm_medium=referral&utm_campaign=python_repo_readme) +- 💬 [Support & Community](https://capmonster.cloud/en/?utm_source=github&utm_medium=referral&utm_campaign=python_repo_readme#support) --- ## ⭐ Star History -If this library helps your automation workflows, please give us a star! - [![Star History Chart](https://api.star-history.com/svg?repos=ZennoLab/capmonstercloud-client-python&type=Date)](https://star-history.com/#ZennoLab/capmonstercloud-client-python&Date) --- ## 📄 License -[MIT](LICENSE) © [ZennoLab](https://zennolab.com/) / [CapMonster Cloud](https://capmonster.cloud/) +[MIT](LICENSE) © [ZennoLab](https://zennolab.com/) / [CapMonster Cloud](https://capmonster.cloud/en/?utm_source=github&utm_medium=referral&utm_campaign=python_repo_readme)