A robust, ready-to-use Python template for bypassing reCAPTCHA v2, reCAPTCHA v3, and Cloudflare Turnstile in web scraping projects using Botasaurus (for anti-detection) and CapSolver (for solving).
- Seamless Integration: Combines the power of Botasaurus's anti-detection with CapSolver's API.
- Multi-Captcha Support: Ready-to-use examples for reCAPTCHA v2, v3, and Cloudflare Turnstile.
- Clean Architecture: Separated configuration, helper functions, and examples for easy maintenance.
- Token Injection: Demonstrates how to correctly inject the solved token back into the browser context using Botasaurus.
- Python 3.8+
- A CapSolver API Key (Get yours from the CapSolver Dashboard)
Clone the repository and install dependencies:
git clone https://github.com/your-username/this-repo.git
cd this-repo
pip install -r requirements.txtCreate a .env file in the project root and add your API key:
# .env
CAPSOLVER_API_KEY=CAP-YOUR_API_KEY_HEREExecute any of the example scripts located in the examples/ directory:
# Example for reCAPTCHA v2
python examples/recaptcha_v2.py
# Example for Cloudflare Turnstile
python examples/turnstile.py.
βββ README.md
βββ LICENSE
βββ CONTRIBUTING.md
βββ requirements.txt
βββ .env (ignored by git)
βββ src/
βββ config.py # Loads API key and defines endpoints
βββ capsolver_helper.py # Core functions for creating and polling CapSolver tasks
βββ examples/
βββ recaptcha_v2.py # Complete example for reCAPTCHA v2
βββ recaptcha_v3.py # Complete example for reCAPTCHA v3
βββ turnstile.py # Complete example for Cloudflare Turnstile
The core logic is split into configuration and the solving helper.
Handles environment variable loading and API endpoint definitions.
# src/config.py
import os
from pathlib import Path
from dotenv import load_dotenv
ROOT_DIR = Path(__file__).parent.parent
load_dotenv(ROOT_DIR / ".env")
class Config:
"""Configuration class for CapSolver integration."""
CAPSOLVER_API_KEY: str = os.getenv("CAPSOLVER_API_KEY", "")
CAPSOLVER_API_URL = "https://api.capsolver.com"
CREATE_TASK_ENDPOINT = f"{CAPSOLVER_API_URL}/createTask"
GET_RESULT_ENDPOINT = f"{CAPSOLVER_API_URL}/getTaskResult"
@classmethod
def validate(cls) -> bool:
if not cls.CAPSOLVER_API_KEY:
print("Error: CAPSOLVER_API_KEY not set! Check your .env file.")
return False
return TrueContains the reusable functions for solving different captcha types.
# src/capsolver_helper.py (Simplified for README)
import time
import requests
from src.config import Config
def _poll_task_result(payload: dict, timeout: int) -> dict:
# ... (Polling logic as described in the article) ...
pass
def solve_recaptcha_v2(website_url: str, website_key: str, is_invisible: bool = False) -> dict:
"""Solves reCAPTCHA v2 and returns the gRecaptchaResponse token."""
if not Config.validate():
raise Exception("Invalid configuration")
task = {
"type": "ReCaptchaV2TaskProxyLess",
"websiteURL": website_url,
"websiteKey": website_key,
"isInvisible": is_invisible
}
# ... (Task creation and polling via _poll_task_result) ...
# Returns {'gRecaptchaResponse': '...'}
pass
def solve_recaptcha_v3(website_url: str, website_key: str, page_action: str) -> dict:
"""Solves reCAPTCHA v3 and returns the gRecaptchaResponse token."""
# ... (Implementation similar to v2, but with pageAction) ...
# Returns {'gRecaptchaResponse': '...'}
pass
def solve_turnstile(website_url: str, website_key: str, action: str = None) -> dict:
"""Solves Cloudflare Turnstile and returns the token."""
# ... (Implementation similar to v2, but with AntiTurnstileTaskProxyLess) ...
# Returns {'token': '...'}
pass| Practice | Description |
|---|---|
| Immediate Use | Captcha tokens expire quickly (~2 minutes). Inject and submit immediately after receiving the token. |
| Error Handling | Always wrap API calls in try...except blocks to handle network or API failures gracefully. |
| Rate Limiting | Use driver.sleep() between actions to mimic human behavior and avoid triggering anti-bot measures. |
| Configuration | Use the Config.validate() method before making any API calls. |
Boost your automation budget instantly! Use bonus code CAPN when topping up your CapSolver account to get an extra 5% bonus on every rechargeβwith no limits!
Redeem it now in your CapSolver Dashboard!
We welcome contributions! Please see the CONTRIBUTING.md for details on how to submit pull requests, report bugs, and suggest features.
This project is licensed under the MIT License - see the LICENSE file for details.
