Skip to content

Commit c8793f6

Browse files
alperensertclaude
alperensert
and
claude
committed
docs: update README and API reference for new features
Rewrite README with cleaner layout, categorized task tables, and code examples for new features. Update client.md with new methods and corrected retry_delay default. Update recaptcha.md with new fields. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent dd13b59 commit c8793f6

File tree

3 files changed

+224
-88
lines changed

3 files changed

+224
-88
lines changed

‎README.md‎

Lines changed: 168 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1,128 +1,210 @@
1-
# 🤖 Capmonster Python
1+
# Capmonster Python
22

3-
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/capmonster-python?style=for-the-badge)
4-
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/alperensert/capmonster_python?style=for-the-badge)
5-
![GitHub last commit](https://img.shields.io/github/last-commit/alperensert/capmonster_python?style=for-the-badge)
6-
![GitHub Release](https://img.shields.io/github/v/release/alperensert/capmonster_python?style=for-the-badge)
7-
![GitHub Repo stars](https://img.shields.io/github/stars/alperensert/capmonster_python?style=for-the-badge&color=rgb(255%2C%20255%2C%20143)&cacheSeconds=3600)
3+
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/capmonster-python?style=for-the-badge)](https://pypi.org/project/capmonster-python/)
4+
[![GitHub Release](https://img.shields.io/github/v/release/alperensert/capmonster_python?style=for-the-badge)](https://github.com/alperensert/capmonster_python/releases)
5+
[![GitHub last commit](https://img.shields.io/github/last-commit/alperensert/capmonster_python?style=for-the-badge)](https://github.com/alperensert/capmonster_python/commits/master)
6+
[![GitHub Repo stars](https://img.shields.io/github/stars/alperensert/capmonster_python?style=for-the-badge&color=rgb(255%2C%20255%2C%20143)&cacheSeconds=3600)](https://github.com/alperensert/capmonster_python)
87

9-
A modern, strongly typed, async-friendly Python SDK for solving CAPTCHA challenges
10-
using [Capmonster.Cloud](https://capmonster.cloud/).
8+
A modern, strongly-typed Python SDK for [CapMonster Cloud](https://capmonster.cloud/) — solve reCAPTCHA, Turnstile, GeeTest, and 20+ other CAPTCHA types with both sync and async support.
119

12-
Supports reCAPTCHA v2 & v3, Cloudflare Turnstile, GeeTest (v3 & v4) and [much more](#-supported-captcha-types).
10+
## Installation
1311

14-
---
15-
16-
## ✨ Features
12+
```bash
13+
pip install capmonster_python
14+
```
1715

18-
- ✅ Fully typed Pydantic v2 models
19-
- 🔁 Both sync and async API support
20-
- 🔐 Proxy and User-Agent configuration
21-
- 📦 Supports the most common CAPTCHA types
22-
- 📚 Intuitive API with powerful task building
16+
> [!IMPORTANT]
17+
> This is **v4** of Capmonster Python, which includes breaking changes from v3.x.
18+
> For the legacy API: `pip install capmonster_python==3.2`
2319
24-
---
20+
## Quick Start
2521

26-
## 🔧 Installation
22+
```python
23+
from capmonster_python import CapmonsterClient, RecaptchaV2Task
2724

28-
```bash
29-
pip install capmonster_python
30-
```
25+
client = CapmonsterClient(api_key="YOUR_API_KEY")
3126

32-
> [!IMPORTANT]
33-
> You're viewing the documentation for **Capmonster Python v4**, which includes breaking changes. If you prefer the
34-
> old syntax used in versions prior to 4.x, you can continue using it by installing the legacy version:
35-
> ```pip install capmonster_python==3.2```
27+
task = RecaptchaV2Task(
28+
websiteURL="https://example.com",
29+
websiteKey="SITE_KEY_HERE"
30+
)
3631

37-
## 🚀 Quick Start
32+
result = client.solve(task)
33+
print(result) # {"gRecaptchaResponse": "03AGdBq24..."}
34+
```
3835

39-
### Async Example
36+
### Async
4037

4138
```python
4239
import asyncio
4340
from capmonster_python import CapmonsterClient, RecaptchaV3Task
4441

45-
4642
async def main():
47-
client = CapmonsterClient(api_key="YOUR_API_KEY")
48-
49-
task = RecaptchaV3Task(
50-
websiteURL="https://example.com",
51-
websiteKey="SITE_KEY_HERE",
52-
minScore=0.5,
53-
pageAction="verify"
54-
)
55-
56-
task_id = await client.create_task_async(task)
57-
result = await client.join_task_result_async(task_id)
58-
print(result)
59-
43+
async with CapmonsterClient(api_key="YOUR_API_KEY") as client:
44+
task = RecaptchaV3Task(
45+
websiteURL="https://example.com",
46+
websiteKey="SITE_KEY_HERE",
47+
minScore=0.5,
48+
pageAction="verify"
49+
)
50+
result = await client.solve_async(task)
51+
print(result)
6052

6153
asyncio.run(main())
62-
6354
```
6455

65-
### Sync Example
56+
### With Proxy
6657

6758
```python
68-
from capmonster_python import CapmonsterClient, RecaptchaV2Task
59+
from capmonster_python import CapmonsterClient, RecaptchaV2Task, ProxyPayload
6960

70-
client = CapmonsterClient(api_key="<YOUR_API_KEY>")
61+
client = CapmonsterClient(api_key="YOUR_API_KEY")
7162

7263
task = RecaptchaV2Task(
7364
websiteURL="https://example.com",
74-
websiteKey="SITE_KEY_HERE"
65+
websiteKey="SITE_KEY_HERE",
66+
proxy=ProxyPayload(
67+
proxyType="http",
68+
proxyAddress="1.2.3.4",
69+
proxyPort=8080,
70+
proxyLogin="user",
71+
proxyPassword="pass"
72+
)
7573
)
7674

77-
task_id = client.create_task(task)
78-
result = client.join_task_result(task_id)
79-
print(result)
75+
result = client.solve(task)
76+
```
77+
78+
## Client API
79+
80+
```python
81+
CapmonsterClient(api_key, timeout=30.0, max_retries=120, retry_delay=2.0)
8082
```
8183

82-
---
84+
| Method | Description |
85+
|--------|-------------|
86+
| `solve(task)` | Create task and poll until solved |
87+
| `create_task(task)` | Create a task, returns `task_id` |
88+
| `join_task_result(task_id)` | Poll until result is ready |
89+
| `get_task_result(task_id)` | Single poll (no waiting) |
90+
| `get_balance()` | Get account balance |
91+
| `get_user_agent()` | Get current valid User-Agent string |
92+
| `report_incorrect_image(task_id)` | Report bad image captcha solution |
93+
| `report_incorrect_token(task_id)` | Report bad token captcha solution |
94+
95+
All methods have async variants with the `_async` suffix (e.g. `solve_async`, `get_balance_async`).
96+
97+
Both sync and async context managers are supported for proper connection cleanup.
98+
99+
## Supported CAPTCHA Types
83100

84-
## 🧠 Supported CAPTCHA Types
101+
### reCAPTCHA
85102

86-
Capmonster Python v4 supports a wide range of CAPTCHA formats — from mainstream challenges like reCAPTCHA and Turnstile
87-
to enterprise-grade shields like Imperva and DataDome. Each task supports full Pydantic validation ✅ and both sync and
88-
async clients 🔄 unless noted.
103+
| CAPTCHA Type | Class | Proxy |
104+
|---|---|---|
105+
| reCAPTCHA v2 | `RecaptchaV2Task` | Optional |
106+
| reCAPTCHA v2 Enterprise | `RecaptchaV2EnterpriseTask` | Optional |
107+
| reCAPTCHA v3 | `RecaptchaV3Task` | No |
108+
| reCAPTCHA v3 Enterprise | `RecaptchaV3EnterpriseTask` | No |
109+
| reCAPTCHA Click | `RecaptchaClickTask` | Optional |
89110

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

110-
## 🧩 Advanced Usage
113+
| CAPTCHA Type | Class | Proxy |
114+
|---|---|---|
115+
| Turnstile | `TurnstileTask` | No |
116+
| Turnstile Challenge (cf_clearance) | `TurnstileCloudFlareTask` | Required |
117+
| Turnstile Waiting Room | `TurnstileWaitingRoomTask` | Required |
118+
119+
### Image-Based
120+
121+
| CAPTCHA Type | Class | Proxy |
122+
|---|---|---|
123+
| Image-to-Text OCR | `ImageToTextTask` | No |
124+
| Complex Image (reCAPTCHA grid) | `ComplexImageRecaptchaTask` | No |
125+
| Complex Image Recognition | `ComplexImageRecognitionTask` | No |
126+
127+
### Behavioral / Interactive
128+
129+
| CAPTCHA Type | Class | Proxy |
130+
|---|---|---|
131+
| GeeTest v3 | `GeeTestV3Task` | Optional |
132+
| GeeTest v4 | `GeeTestV4Task` | Optional |
133+
| FunCaptcha (Arkose Labs) | `FunCaptchaTask` | Optional |
134+
| Hunt | `HuntTask` | Optional |
135+
136+
### Enterprise Protection
137+
138+
| CAPTCHA Type | Class | Proxy |
139+
|---|---|---|
140+
| DataDome | `DataDomeTask` | Required |
141+
| Imperva (Incapsula) | `ImpervaTask` | Required |
142+
| Amazon WAF | `AmazonTask` | Optional |
143+
| TSPD | `TSPDTask` | Optional |
144+
145+
### Platform-Specific
146+
147+
| CAPTCHA Type | Class | Proxy |
148+
|---|---|---|
149+
| Binance | `BinanceTask` | Required |
150+
| Temu | `TemuTask` | No |
151+
| TenDI | `TenDITask` | Required |
152+
153+
### Other
154+
155+
| CAPTCHA Type | Class | Proxy |
156+
|---|---|---|
157+
| Altcha | `AltchaTask` | No |
158+
| Basilisk | `BasiliskTask` | No |
159+
| Castle | `CastleTask` | No |
160+
| MTCaptcha | `MTCaptchaTask` | Optional |
161+
| Prosopo | `ProsopoTask` | Optional |
162+
| Yidun | `YidunTask` | Optional |
163+
164+
> Don't see your captcha type? Use `VanillaTaskPayload` to build custom task payloads without waiting for an SDK update.
165+
166+
## Advanced Usage
167+
168+
### Callback URLs
169+
170+
```python
171+
result = client.solve(task, callback_url="https://yoursite.com/callback")
172+
```
173+
174+
### Report Incorrect Solutions
175+
176+
```python
177+
task_id = client.create_task(task)
178+
result = client.join_task_result(task_id)
179+
180+
# If the token was rejected by the target site:
181+
client.report_incorrect_token(task_id)
182+
```
183+
184+
### Fresh Token Generation
185+
186+
Use `nocache=True` on reCAPTCHA tasks to prevent cached token reuse:
187+
188+
```python
189+
task = RecaptchaV2Task(
190+
websiteURL="https://example.com",
191+
websiteKey="SITE_KEY_HERE",
192+
nocache=True
193+
)
194+
```
111195

112-
- Callback URLs are supported during task creation.
113-
- Includes auto-retry loop for polling results (up to 120s)
196+
## Documentation
114197

115-
## 💬 Community & Support
198+
Full API reference available at [alperensert.github.io/capmonster_python](https://alperensert.github.io/capmonster_python/).
116199

117-
Need help or have a question?
200+
## Support
118201

119-
- 📧 Contact: business@alperen.io
120-
- 🐛 Found a bug? [Open an issue](https://github.com/alperensert/capmonster_python/issues)
202+
- Found a bug? [Open an issue](https://github.com/alperensert/capmonster_python/issues)
203+
- Contact: business@alperen.io
121204

122-
> [!NOTE]
123-
> Community support is intended only for questions and issues related to this project. Custom usage scenarios,
124-
> integrations, or application-specific logic are outside the scope of support.
205+
> [!NOTE]
206+
> Support is limited to questions and issues related to this project. Custom integrations and application-specific logic are outside the scope of support.
125207
126-
## 📄 License
208+
## License
127209

128-
This project is licensed under the [MIT License](/LICENSE).
210+
[MIT License](/LICENSE)

‎docs/reference/client.md‎

Lines changed: 49 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,15 @@ The main client for interacting with the Capmonster Cloud API. Supports both syn
55
## Constructor
66

77
```python
8-
CapmonsterClient(api_key: str, timeout: float = 30.0, max_retries: int = 120, retry_delay: float = 1.0)
8+
CapmonsterClient(api_key: str, timeout: float = 30.0, max_retries: int = 120, retry_delay: float = 2.0)
99
```
1010

1111
| Parameter | Type | Default | Description |
1212
|-----------|------|---------|-------------|
1313
| `api_key` | `str` | **required** | Your Capmonster Cloud API key. |
1414
| `timeout` | `float` | `30.0` | HTTP request timeout in seconds. |
1515
| `max_retries` | `int` | `120` | Maximum number of polling attempts in `join_task_result` / `solve`. |
16-
| `retry_delay` | `float` | `1.0` | Delay in seconds between polling attempts. |
16+
| `retry_delay` | `float` | `2.0` | Delay in seconds between polling attempts. |
1717

1818
## Context Manager
1919

@@ -119,3 +119,50 @@ async def solve_async(self, task: TaskPayload, callback_url: str | None = None)
119119
| `callback_url` | `str \| None` | `None` | Optional callback URL for task completion. |
120120
121121
**Returns:** `dict` — The solution dictionary from the completed task.
122+
123+
---
124+
125+
### `report_incorrect_image`
126+
127+
Reports an incorrect image captcha solution.
128+
129+
```python
130+
def report_incorrect_image(self, task_id: int) -> None
131+
async def report_incorrect_image_async(self, task_id: int) -> None
132+
```
133+
134+
| Parameter | Type | Description |
135+
|-----------|------|-------------|
136+
| `task_id` | `int` | The task identifier to report. |
137+
138+
**Raises:** `CapmonsterAPIException` if the API returns an error.
139+
140+
---
141+
142+
### `report_incorrect_token`
143+
144+
Reports an incorrect token captcha solution (reCAPTCHA, GeeTest, Turnstile, etc.).
145+
146+
```python
147+
def report_incorrect_token(self, task_id: int) -> None
148+
async def report_incorrect_token_async(self, task_id: int) -> None
149+
```
150+
151+
| Parameter | Type | Description |
152+
|-----------|------|-------------|
153+
| `task_id` | `int` | The task identifier to report. |
154+
155+
**Raises:** `CapmonsterAPIException` if the API returns an error.
156+
157+
---
158+
159+
### `get_user_agent`
160+
161+
Fetches the current valid Windows User-Agent string from CapMonster Cloud.
162+
163+
```python
164+
def get_user_agent(self) -> str
165+
async def get_user_agent_async(self) -> str
166+
```
167+
168+
**Returns:** `str` — The current User-Agent string to use with captcha tasks.

0 commit comments

Comments
 (0)