0
# Image Captchas
1

2
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.
3

4
## Capabilities
5

6
### Normal Image Captcha
7

8
Solves traditional text-based image captchas where users need to type the characters shown in the image.
9

10
```python { .api }
11
def normal(self, file, **kwargs):
12
    """
13
    Solve normal image captcha.
14
    
15
    Parameters:
16
    - file (str): Path to captcha image file or base64-encoded image
17
    - phrase (int): 0=one word, 1=two+ words (default: 0)
18
    - numeric (int): 0=not specified, 1=numbers only, 2=letters only, 
19
                    3=numbers OR letters, 4=numbers AND letters (default: 0)
20
    - minLen (int): Minimum number of symbols (1-20, default: 0)
21
    - maxLen (int): Maximum number of symbols (1-20, default: 0) 
22
    - caseSensitive (int): 0=not case sensitive, 1=case sensitive (default: 0)
23
    - calc (int): 0=not specified, 1=math calculation required (default: 0)
24
    - lang (str): Language code (see 2captcha.com language list)
25
    - hintText (str): Text hint for worker (max 140 chars)
26
    - hintImg (str): Path to hint image (max 400x150px, 100KB)
27
    - softId (int): Software developer ID
28
    - callback (str): Pingback URL for result notification
29
    
30
    Returns:
31
    dict: {'captchaId': str, 'code': str}
32
    """
33
```
34

35
### Grid Captcha
36

37
Solves grid-based captchas where users need to click on specific areas or objects within an image grid.
38

39
```python { .api }
40
def grid(self, file, **kwargs):
41
    """
42
    Solve grid/reCAPTCHA image selection captcha.
43
    
44
    Parameters:
45
    - file (str): Path to captcha image file or base64-encoded image (required)
46
    - hintText (str): Text describing what to select (required if no hintImg)
47
    - hintImg (str): Path to hint image showing what to select (required if no hintText)
48
    - rows (int): Number of grid rows (default: auto-detect)
49
    - cols (int): Number of grid columns (default: auto-detect)
50
    - previousId (str): ID of previous captcha for chained solving
51
    - canSkip (int): 1=can skip if no matching images, 0=must select (default: 0)
52
    - lang (str): Language code for hint text
53
    - softId (int): Software developer ID  
54
    - callback (str): Pingback URL for result notification
55
    - proxy (dict): Proxy configuration {'type': 'HTTPS', 'uri': 'login:pass@ip:port'}
56
    
57
    Returns:
58
    dict: {'captchaId': str, 'code': str} - code contains clicked cell numbers
59
    """
60
```
61

62
### Coordinates Captcha
63

64
Solves coordinate-based captchas where users need to click on specific points within an image.
65

66
```python { .api }
67
def coordinates(self, file, **kwargs):
68
    """
69
    Solve coordinate/click captcha.
70
    
71
    Parameters:
72
    - file (str): Path to captcha image file or base64-encoded image (required)
73
    - hintText (str): Text describing where to click
74
    - hintImg (str): Path to hint image showing where to click
75
    - lang (str): Language code for hint text
76
    - softId (int): Software developer ID
77
    - callback (str): Pingback URL for result notification
78
    
79
    Returns:
80
    dict: {'captchaId': str, 'code': str} - code contains x,y coordinates
81
    """
82
```
83

84
### Canvas Captcha
85

86
Solves canvas-based captchas where users need to draw or trace specific shapes or patterns.
87

88
```python { .api }
89
def canvas(self, file, **kwargs):
90
    """
91
    Solve canvas drawing captcha.
92
    
93
    Parameters:
94
    - file (str): Path to captcha image file or base64-encoded image (required)
95
    - hintText (str): Text describing what to draw (required if no hintImg)
96
    - hintImg (str): Path to hint image showing what to draw (required if no hintText)
97
    - canSkip (int): 1=can skip if unable to draw, 0=must draw (default: 0)
98
    - lang (str): Language code for hint text
99
    - softId (int): Software developer ID
100
    - callback (str): Pingback URL for result notification
101
    
102
    Returns:
103
    dict: {'captchaId': str, 'code': str} - code contains drawing coordinates
104
    """
105
```
106

107
### Rotate Captcha
108

109
Solves image rotation captchas where users need to rotate images to the correct orientation.
110

111
```python { .api }
112
def rotate(self, files, **kwargs):
113
    """
114
    Solve image rotation captcha.
115
    
116
    Parameters:
117
    - files (str|dict): Single image path/base64 or dict mapping filenames to paths
118
    - angle (int): Rotation step in degrees (default: auto-detect)
119
    - lang (str): Language code for any text hints
120
    - hintImg (str): Path to hint image showing correct orientation
121
    - hintText (str): Text hint describing correct orientation
122
    - softId (int): Software developer ID
123
    - callback (str): Pingback URL for result notification
124
    - proxy (dict): Proxy configuration {'type': 'HTTPS', 'uri': 'login:pass@ip:port'}
125
    
126
    Returns:
127
    dict: {'captchaId': str, 'code': str} - code contains rotation angles
128
    """
129
```
130

131
## Usage Examples
132

133
### Normal Text Captcha
134

135
```python
136
from twocaptcha import TwoCaptcha
137

138
solver = TwoCaptcha('your_api_key')
139

140
# Simple text captcha
141
result = solver.normal('path/to/captcha.jpg')
142
print(f"Text: {result['code']}")
143

144
# Math captcha with constraints
145
result = solver.normal(
146
    'math_captcha.jpg',
147
    calc=1,           # Math calculation required
148
    numeric=1,        # Numbers only
149
    minLen=1,         # At least 1 digit
150
    maxLen=3          # At most 3 digits
151
)
152
print(f"Answer: {result['code']}")
153

154
# Case-sensitive with hint
155
result = solver.normal(
156
    'complex_captcha.jpg',
157
    caseSensitive=1,
158
    hintText='Type only the red letters',
159
    lang='en'
160
)
161
print(f"Text: {result['code']}")
162
```
163

164
### Grid Selection Captcha
165

166
```python
167
from twocaptcha import TwoCaptcha
168

169
solver = TwoCaptcha('your_api_key')
170

171
# reCAPTCHA-style image selection
172
result = solver.grid(
173
    'recaptcha_grid.jpg',
174
    hintText='Select all images with traffic lights',
175
    rows=3,
176
    cols=3
177
)
178
print(f"Selected cells: {result['code']}")
179

180
# Custom grid with hint image
181
result = solver.grid(
182
    'custom_grid.jpg',
183
    hintImg='hint_image.jpg',
184
    canSkip=1  # Allow skipping if no matches
185
)
186
print(f"Selected: {result['code']}")
187
```
188

189
### Click Coordinates
190

191
```python
192
from twocaptcha import TwoCaptcha
193

194
solver = TwoCaptcha('your_api_key')
195

196
# Click on specific object
197
result = solver.coordinates(
198
    'click_captcha.jpg',
199
    hintText='Click on the cat'
200
)
201
print(f"Click coordinates: {result['code']}")  # "x=123,y=456"
202
```
203

204
### Canvas Drawing
205

206
```python
207
from twocaptcha import TwoCaptcha
208

209
solver = TwoCaptcha('your_api_key')
210

211
# Draw a line or shape  
212
result = solver.canvas(
213
    'canvas_captcha.jpg',
214
    hintText='Draw a line from point A to point B'
215
)
216
print(f"Drawing path: {result['code']}")
217
```
218

219
### Image Rotation
220

221
```python
222
from twocaptcha import TwoCaptcha
223

224
solver = TwoCaptcha('your_api_key')
225

226
# Single image rotation
227
result = solver.rotate('rotated_image.jpg')
228
print(f"Rotation angle: {result['code']}")
229

230
# Multiple images
231
result = solver.rotate({
232
    'img1': 'path/to/image1.jpg',
233
    'img2': 'path/to/image2.jpg'
234
})
235
print(f"Rotations: {result['code']}")
236
```
237

238
### Error Handling
239

240
```python
241
from twocaptcha import TwoCaptcha, ValidationException
242

243
solver = TwoCaptcha('your_api_key')
244

245
try:
246
    result = solver.normal('captcha.jpg', minLen=5, maxLen=3)  # Invalid: min > max
247
except ValidationException as e:
248
    print(f"Validation error: {e}")
249

250
try:
251
    result = solver.grid('grid.jpg')  # Missing required hint
252
except ValidationException as e:
253
    print(f"Missing hint: {e}")
254
```