Capmonster Python

A modern, strongly-typed Python SDK for CapMonster Cloud — solve reCAPTCHA, Turnstile, GeeTest, and 20+ other CAPTCHA types with both sync and async support.

Installation

pip install capmonster_python

[!IMPORTANT] This is v4 of Capmonster Python, which includes breaking changes from v3.x. For the legacy API: pip install capmonster_python==3.2

Quick Start

from capmonster_python import CapmonsterClient, RecaptchaV2Task

client = CapmonsterClient(api_key="YOUR_API_KEY")

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

result = client.solve(task)
print(result)  # {"gRecaptchaResponse": "03AGdBq24..."}

Async

import asyncio
from capmonster_python import CapmonsterClient, RecaptchaV3Task

async def main():
    async with CapmonsterClient(api_key="YOUR_API_KEY") as client:
        task = RecaptchaV3Task(
            websiteURL="https://example.com",
            websiteKey="SITE_KEY_HERE",
            minScore=0.5,
            pageAction="verify"
        )
        result = await client.solve_async(task)
        print(result)

asyncio.run(main())

With Proxy

from capmonster_python import CapmonsterClient, RecaptchaV2Task, ProxyPayload

client = CapmonsterClient(api_key="YOUR_API_KEY")

task = RecaptchaV2Task(
    websiteURL="https://example.com",
    websiteKey="SITE_KEY_HERE",
    proxy=ProxyPayload(
        proxyType="http",
        proxyAddress="1.2.3.4",
        proxyPort=8080,
        proxyLogin="user",
        proxyPassword="pass"
    )
)

result = client.solve(task)

Client API

CapmonsterClient(api_key, timeout=30.0, max_retries=120, retry_delay=2.0)

All methods have async variants with the _async suffix (e.g. solve_async, get_balance_async).

Both sync and async context managers are supported for proper connection cleanup.

Supported CAPTCHA Types

reCAPTCHA

Cloudflare

Image-Based

Behavioral / Interactive

Enterprise Protection

Platform-Specific

Other

Don't see your captcha type? Use VanillaTaskPayload to build custom task payloads without waiting for an SDK update.

Advanced Usage

Callback URLs

result = client.solve(task, callback_url="https://yoursite.com/callback")

Report Incorrect Solutions

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

# If the token was rejected by the target site:
client.report_incorrect_token(task_id)

Fresh Token Generation

Use nocache=True on reCAPTCHA tasks to prevent cached token reuse:

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

Documentation

Full API reference available at alperensert.github.io/capmonster_python.

Support

• Found a bug? Open an issue
• Contact: business@alperen.io

[!NOTE] Support is limited to questions and issues related to this project. Custom integrations and application-specific logic are outside the scope of support.

License

MIT License