capmonster-python

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)

Method	Description
solve(task)	Create task and poll until solved
create_task(task)	Create a task, returns task_id
join_task_result(task_id)	Poll until result is ready
get_task_result(task_id)	Single poll (no waiting)
get_balance()	Get account balance
get_user_agent()	Get current valid User-Agent string
report_incorrect_image(task_id)	Report bad image captcha solution
report_incorrect_token(task_id)	Report bad token captcha solution

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

CAPTCHA Type	Class	Proxy
reCAPTCHA v2	RecaptchaV2Task	Optional
reCAPTCHA v2 Enterprise	RecaptchaV2EnterpriseTask	Optional
reCAPTCHA v3	RecaptchaV3Task	No
reCAPTCHA v3 Enterprise	RecaptchaV3EnterpriseTask	No
reCAPTCHA Click	RecaptchaClickTask	Optional

Cloudflare

CAPTCHA Type	Class	Proxy
Turnstile	TurnstileTask	No
Turnstile Challenge (cf_clearance)	TurnstileCloudFlareTask	Required
Turnstile Waiting Room	TurnstileWaitingRoomTask	Required

Image-Based

CAPTCHA Type	Class	Proxy
Image-to-Text OCR	ImageToTextTask	No
Complex Image (reCAPTCHA grid)	ComplexImageRecaptchaTask	No
Complex Image Recognition	ComplexImageRecognitionTask	No

Behavioral / Interactive

CAPTCHA Type	Class	Proxy
GeeTest v3	GeeTestV3Task	Optional
GeeTest v4	GeeTestV4Task	Optional
FunCaptcha (Arkose Labs)	FunCaptchaTask	Optional
Hunt	HuntTask	Optional

Enterprise Protection

CAPTCHA Type	Class	Proxy
DataDome	DataDomeTask	Required
Imperva (Incapsula)	ImpervaTask	Required
Amazon WAF	AmazonTask	Optional
TSPD	TSPDTask	Optional

Platform-Specific

CAPTCHA Type	Class	Proxy
Binance	BinanceTask	Required
Temu	TemuTask	No
TenDI	TenDITask	Required

Other

CAPTCHA Type	Class	Proxy
Altcha	AltchaTask	No
Basilisk	BasiliskTask	No
Castle	CastleTask	No
MTCaptcha	MTCaptchaTask	Optional
Prosopo	ProsopoTask	Optional
Yidun	YidunTask	Optional

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: [e-mail]

[!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