capmonster-python

🤖 Capmonster Python

A modern, strongly typed, async-friendly Python SDK for solving CAPTCHA challenges using Capmonster.Cloud.

Supports reCAPTCHA v2 & v3, Cloudflare Turnstile, GeeTest (v3 & v4) and much more.

✨ Features

• ✅ Fully typed Pydantic v2 models
• 🔁 Both sync and async API support
• 🔐 Proxy and User-Agent configuration
• 📦 Supports the most common CAPTCHA types
• 📚 Intuitive API with powerful task building

🔧 Installation

pip install capmonster_python

[!IMPORTANT]
You're viewing the documentation for Capmonster Python v4, which includes breaking changes. If you prefer the old syntax used in versions prior to 4.x, you can continue using it by installing the legacy version:
pip install capmonster_python==3.2

🚀 Quick Start

Async Example

import asyncio
from capmonster_python import CapmonsterClient, RecaptchaV3Task


async def main():
    client = CapmonsterClient(api_key="YOUR_API_KEY")

    task = RecaptchaV3Task(
        websiteURL="https://example.com",
        websiteKey="SITE_KEY_HERE",
        minScore=0.5,
        pageAction="verify"
    )

    task_id = await client.create_task_async(task)
    result = await client.join_task_result_async(task_id)
    print(result)


asyncio.run(main())

Sync Example

from capmonster_python import CapmonsterClient, RecaptchaV2Task

client = CapmonsterClient(api_key="<YOUR_API_KEY>")

task = RecaptchaV2Task(
    websiteURL="https://example.com",
    websiteKey="SITE_KEY_HERE"
)

task_id = client.create_task(task)
result = client.join_task_result(task_id)
print(result)

🧠 Supported CAPTCHA Types

Capmonster Python v4 supports a wide range of CAPTCHA formats — from mainstream challenges like reCAPTCHA and Turnstile to enterprise-grade shields like Imperva and DataDome. Each task supports full Pydantic validation ✅ and both sync and async clients 🔄 unless noted.

🔖 Category	CAPTCHA Type	Class Name	Proxy Required	Notes
🧩 reCAPTCHA	reCAPTCHA v2	RecaptchaV2Task	Optional	Visible / Invisible supported ✅ 🔄
	reCAPTCHA v2 Enterprise	RecaptchaV2EnterpriseTask	Optional	enterprisePayload & apiDomain ✅ 🔄
	reCAPTCHA v3	RecaptchaV3Task	❌ No	Score-based, proxyless ✅ 🔄
🛡️ Cloudflare	Turnstile (token)	TurnstileTask	❌ No	Lightweight, async-ready ✅ 🔄
	Turnstile (cf_clearance)	TurnstileCloudFlareTask	✅ Yes	Full HTML + proxy required ✅ 🔄
📸 Image-based	Image-to-Text OCR	ImageToTextTask	❌ No	Base64 image + module control ✅ 🔄
	Complex Image (Recaptcha-like)	ComplexImageRecaptchaTask	❌ No	Grid-based, metadata aware ✅ 🔄
	Complex Image Recognition (AI)	ComplexImageRecognitionTask	❌ No	Supports tasks like Shein, OOCL ✅ 🔄
🧠 Human Behavior	GeeTest v3	GeeTestV3Task	Optional	Challenge + gt key + freshness ✅ 🔄
	GeeTest v4	GeeTestV4Task	Optional	initParameters supported ✅ 🔄
🛡️ Enterprise Protection	DataDome	DataDomeTask	✅ Recommended	Cookie & page context needed ✅ 🔄
	Imperva	ImpervaTask	✅ Recommended	Incapsula + Reese84 logic ✅ 🔄
🏦 Platform-Specific	Binance Login	BinanceTask	✅ Yes	validateId for login flow ✅ 🔄
	Temu	TemuTask	❌ No	Cookie-injected behavioral solver ✅ 🔄
	TenDI	TenDITask	✅ Yes	Custom captchaAppId field ✅ 🔄
🧪 Miscellaneous	Prosopo	ProsopoTask	Optional	Used in zk or crypto UIs ✅ 🔄
	Basilisk	BasiliskTask	❌ No	Minimalist site-key puzzle ✅ 🔄

🧩 Advanced Usage

• Callback URLs are supported during task creation.
• Includes auto-retry loop for polling results (up to 120s)

💬 Community & Support

Need help or have a question?

• 📧 Contact: [e-mail]
• 🐛 Found a bug? Open an issue

[!NOTE]
Community support is intended only for questions and issues related to this project. Custom usage scenarios, integrations, or application-specific logic are outside the scope of support.

📄 License

This project is licensed under the MIT License.