0
# 2captcha-python
1

2
Python module for easy integration with the 2Captcha API service to solve various types of captchas including reCAPTCHA, FunCaptcha, GeeTest, hCaptcha, and many others. The library provides a comprehensive solution for automated captcha solving in web scraping, testing, and automation workflows.
3

4
## Package Information
5

6
- **Package Name**: 2captcha-python
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install 2captcha-python`
10
- **Version**: 1.5.1
11
- **License**: MIT
12

13
## Core Imports
14

15
```python
16
from twocaptcha import TwoCaptcha
17
```
18

19
Import exceptions:
20

21
```python
22
from twocaptcha import (
23
    SolverExceptions, 
24
    ValidationException, 
25
    NetworkException, 
26
    ApiException, 
27
    TimeoutException
28
)
29
```
30

31
Import low-level API client:
32

33
```python
34
from twocaptcha import ApiClient
35
```
36

37
## Basic Usage
38

39
```python
40
from twocaptcha import TwoCaptcha
41

42
# Initialize the solver with your API key
43
solver = TwoCaptcha("YOUR_API_KEY")
44

45
# Solve a normal image captcha
46
result = solver.normal('/path/to/captcha.jpg')
47
print(f"Captcha solved: {result['code']}")
48

49
# Solve a reCAPTCHA v2
50
result = solver.recaptcha(
51
    sitekey='6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-',
52
    url='https://www.google.com/recaptcha/api2/demo'
53
)
54
print(f"reCAPTCHA token: {result['code']}")
55

56
# Check account balance
57
balance = solver.balance()
58
print(f"Account balance: ${balance}")
59
```
60

61
## Architecture
62

63
The library is structured around two main classes:
64

65
- **TwoCaptcha**: The primary high-level interface providing specialized methods for each captcha type
66
- **ApiClient**: Low-level HTTP client for direct API communication
67

68
The TwoCaptcha class provides both automatic solving (submit and wait for result) and manual control (separate submit and polling). All captcha solving methods return a dictionary containing the captcha ID and solution code.
69

70
## Capabilities
71

72
### Core Solver API
73

74
Main TwoCaptcha class initialization, core solving methods, account management, and error handling. These provide the foundation for all captcha solving operations.
75

76
```python { .api }
77
class TwoCaptcha:
78
    def __init__(self, apiKey, softId=4580, callback=None, 
79
                defaultTimeout=120, recaptchaTimeout=600, 
80
                pollingInterval=10, server='2captcha.com', 
81
                extendedResponse=None): ...
82
    
83
    def solve(self, timeout=0, polling_interval=0, **kwargs): ...
84
    def send(self, **kwargs): ...
85
    def get_result(self, id_): ...
86
    def balance(self): ...
87
    def report(self, id_, correct): ...
88
```
89

90
[Core Solver API](./core-solver.md)
91

92
### Image Captchas
93

94
Methods for solving various types of image-based captchas including normal text captchas, grid-based selection captchas, coordinate-based click captchas, canvas drawing captchas, and image rotation captchas.
95

96
```python { .api }
97
def normal(self, file, **kwargs): ...
98
def grid(self, file, **kwargs): ...
99
def coordinates(self, file, **kwargs): ...
100
def canvas(self, file, **kwargs): ...
101
def rotate(self, files, **kwargs): ...
102
```
103

104
[Image Captchas](./image-captchas.md)
105

106
### Interactive Captchas
107

108
Methods for solving interactive captcha challenges including reCAPTCHA v2/v3, FunCaptcha, GeeTest, hCaptcha, and other challenge-response systems that require browser interaction.
109

110
```python { .api }
111
def recaptcha(self, sitekey, url, version='v2', 
112
             enterprise=0, **kwargs): ...
113
def funcaptcha(self, sitekey, url, **kwargs): ...
114
def geetest(self, gt, challenge, url, **kwargs): ...
115
def hcaptcha(self, sitekey, url, **kwargs): ...
116
def geetest_v4(self, captcha_id, url, **kwargs): ...
117
```
118

119
[Interactive Captchas](./interactive-captchas.md)
120

121
### Specialized Captchas
122

123
Methods for solving specialized captcha systems including KeyCaptcha, Capy, Lemin, ATB, and various other proprietary captcha solutions.
124

125
```python { .api }
126
def keycaptcha(self, s_s_c_user_id, s_s_c_session_id,
127
              s_s_c_web_server_sign, s_s_c_web_server_sign2, 
128
              url, **kwargs): ...
129
def capy(self, sitekey, url, **kwargs): ...
130
def lemin(self, captcha_id, div_id, url, **kwargs): ...
131
def atb_captcha(self, app_id, api_server, url, **kwargs): ...
132
```
133

134
[Specialized Captchas](./specialized-captchas.md)
135

136
### Cloud Provider Captchas
137

138
Methods for solving captcha systems from major cloud providers including Cloudflare Turnstile, Amazon WAF, and other enterprise-grade protection systems.
139

140
```python { .api }
141
def turnstile(self, sitekey, url, **kwargs): ...
142
def amazon_waf(self, sitekey, iv, context, url, **kwargs): ...
143
def friendly_captcha(self, sitekey, url, **kwargs): ...
144
def mtcaptcha(self, sitekey, url, **kwargs): ...
145
```
146

147
[Cloud Provider Captchas](./cloud-captchas.md)
148

149
### Emerging Captchas
150

151
Methods for solving newer and region-specific captcha systems including Tencent, CutCaptcha, DataDome, CyberSiARA, and Yandex Smart captchas.
152

153
```python { .api }
154
def tencent(self, app_id, url, **kwargs): ...
155
def cutcaptcha(self, misery_key, apikey, url, **kwargs): ...
156
def datadome(self, captcha_url, pageurl, userAgent, proxy, **kwargs): ...
157
def cybersiara(self, master_url_id, pageurl, userAgent, **kwargs): ...
158
def yandex_smart(self, sitekey, url, **kwargs): ...
159
```
160

161
[Emerging Captchas](./emerging-captchas.md)
162

163
### Audio and Text Captchas
164

165
Methods for solving non-visual captcha challenges including audio captchas and text-based questions that require human reasoning or reading comprehension.
166

167
```python { .api }
168
def audio(self, file, lang, **kwargs): ...
169
def text(self, text, **kwargs): ...
170
```
171

172
[Audio and Text Captchas](./audio-text-captchas.md)
173

174
## Exception Types
175

176
```python { .api }
177
class SolverExceptions(Exception):
178
    """Base exception class for all solver-related errors."""
179

180
class ValidationException(SolverExceptions):
181
    """Raised when input parameters fail validation."""
182

183
class NetworkException(SolverExceptions):
184
    """Raised when network communication fails."""
185

186
class ApiException(SolverExceptions):
187
    """Raised when the 2captcha API returns an error."""
188

189
class TimeoutException(SolverExceptions):
190
    """Raised when captcha solving exceeds timeout period."""
191
```
192

193
## Low-Level API Client
194

195
```python { .api }
196
class ApiClient:
197
    def __init__(self, post_url='2captcha.com'):
198
        """
199
        Initialize API client for direct 2captcha API communication.
200
        
201
        Parameters:
202
        - post_url: 2captcha server domain (default: '2captcha.com')
203
        """
204
    
205
    def in_(self, files={}, **kwargs):
206
        """
207
        Send POST request for captcha submission.
208
        
209
        Parameters:
210
        - files (dict): File attachments for image captchas
211
        - **kwargs: API request parameters
212
        
213
        Returns:
214
        str: API response string
215
        
216
        Raises:
217
        NetworkException: Network communication errors
218
        ApiException: API error responses
219
        """
220
    
221
    def res(self, **kwargs):
222
        """
223
        Send GET request for results and other operations.
224
        
225
        Parameters:
226
        - **kwargs: API request parameters
227
        
228
        Returns:
229
        str: API response string
230
        
231
        Raises:
232
        NetworkException: Network communication errors
233
        ApiException: API error responses
234
        """
235
```