A simple and efficient method to integrate the Solvecaptcha captcha-solving service into your code, enabling the automation of solving various types of captchas. Examples of API requests for different captcha types can be found on the Python captcha solver page.
- Python Library for Interacting with the Solvecaptcha API
This package can be installed using Pip:
pip3 install solvecaptcha-pythonor You can install this package directly from GitHub using pip:
pip install git+https://github.com/solvercaptcha/solvecaptcha-python.gitAn instance of Solvecaptcha can be created as follows:
from solvecaptcha import Solvecaptcha
solver = Solvecaptcha('YOUR_API_KEY')Additionally, there are several options available for configuration:
config = {
'server': 'solvecaptcha.com',
'apiKey': 'YOUR_API_KEY',
'callback': 'https://your.site/result-receiver',
'defaultTimeout': 120,
'recaptchaTimeout': 600,
'pollingInterval': 10,
'extendedResponse': False
}
solver = Solvecaptcha(**config)| Option | Default value | Description |
|---|---|---|
| server | solvecaptcha.com |
API server. You can configure it to solvecaptcha.com if your account is registered on this platform. |
| callback | - | The URL of your web server that receives the captcha recognition result. This URL must first be registered in your account's pingback settings. |
| defaultTimeout | 120 | Polling timeout in seconds for all captcha types except reCAPTCHA. Specifies the duration for which the module attempts to retrieve the response from the res.php API endpoint. |
| recaptchaTimeout | 600 | Polling timeout for reCAPTCHA in seconds. Specifies the duration for which the module attempts to retrieve the response from the res.php API endpoint. |
| pollingInterval | 10 | Interval in seconds between requests to the res.php API endpoint. It is not recommended to set a value lower than 5 seconds. |
| extendedResponse | None | Set to True to receive the response with additional fields or in a more structured format (enables JSON response from the res.php API endpoint). Recommended for ClickCaptcha and Canvas. |
Important
Once callback is defined for the Solvecaptcha instance, all methods return only the captcha ID and DO NOT poll the API to get the result. The result will be sent to the callback URL.
To get the answer manually, use the get_result method.
When submitting any image-based CAPTCHA, you can provide additional options to assist Solvecaptcha workers in solving it correctly.
| Option | Default Value | Description |
|---|---|---|
| numeric | 0 | Specifies whether the captcha consists only of numbers or includes other symbols. More details are available in the API documentation. |
| minLen | 0 | Sets the minimum length of the expected answer. |
| maxLen | 0 | Sets the maximum length of the expected answer. |
| phrase | 0 | Indicates whether the response consists of multiple words. |
| caseSensitive | 0 | Determines if the response must match the original case. |
| calc | 0 | Specifies if the captcha involves a mathematical calculation. |
| lang | - | Defines the language of the captcha. Refer to the list of supported languages. |
| hintImg | - | Provides an additional image as a hint for workers alongside the captcha. |
| hintText | - | Displays a text hint or task description for workers along with the captcha. |
Below, you can find basic examples for each captcha type. For more examples with all available options, check the examples directory.
To solve a standard captcha (distorted text on an image), use the following method. This method can also be applied for text recognition in any image.
result = solver.normal('path/to/captcha.jpg', param1=..., ...)
# OR
result = solver.normal('https://site-with-captcha.com/path/to/captcha.jpg', param1=..., ...)result = solver.audio('path/to/captcha.mp3', lang = 'lang', param1=..., ...)
# OR
result = solver.audio('https://site-with-captcha.com/path/to/captcha.mp3', lang = 'lang', param1=..., ...)This method can be used to solve captchas that require answering a question presented in plain text.
result = solver.text('If tomorrow is Saturday, what day is today?', param1=..., ...)Use the following method to solve reCAPTCHA V2 and retrieve a token for bypassing the protection.
result = solver.recaptcha(sitekey='6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-',
url='https://mysite.com/page/with/recaptcha',
param1=..., ...)This method offers a reCAPTCHA V3 solver and returns a token.
result = solver.recaptcha(sitekey='6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-',
url='https://mysite.com/page/with/recaptcha-v3',
version='v3',
param1=..., ...)FunCaptcha (Arkoselabs) solving method that returns a token.
result = solver.funcaptcha(sitekey='6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-',
url='https://mysite.com/page/with/funcaptcha',
param1=..., ...)Method for solving GeeTest puzzle captcha. Returns a set of tokens in JSON format.
result = solver.geetest(gt='f1ab2cdefa3456789012345b6c78d90e',
challenge='12345678abc90123d45678ef90123a456b',
url='https://www.site.com/page/',
param1=..., ...)Use this method to solve GeeTest v4. The response is returned in JSON format.
result = solver.geetest_v4(captcha_id='e392e1d7fd421dc63325744d5a2b9c73',
url='https://www.site.com/page/',
param1=..., ...)Use this method to solve Cloudflare Turnstile. The response is returned as JSON containing the token.
result = solver.turnstile(sitekey='0x1AAAAAAAAkg0s2VIOD34y5',
url='http://mysite.com/',
data='foo',
pagedata='bar',
action='challenge',
useragent='Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36')Token-based method for solving KeyCaptcha.
result = solver.keycaptcha(s_s_c_user_id=10,
s_s_c_session_id='493e52c37c10c2bcdf4a00cbc9ccd1e8',
s_s_c_web_server_sign='9006dc725760858e4c0715b835472f22-pz-',
s_s_c_web_server_sign2='2ca3abe86d90c6142d5571db98af6714',
url='https://www.keycaptcha.ru/demo-magnetic/',
param1=..., ...)The grid method was initially known as the Old reCAPTCHA V2 method. It can be used to bypass any captcha that requires selecting specific grid boxes on an image. Returns the numbers of the selected boxes.
result = solver.grid('path/to/captcha.jpg', param1=..., ...)The ClickCaptcha method returns the coordinates of specific points on the captcha image. It is useful when solving captchas that require clicking on designated areas within the image.
result = solver.coordinates('path/to/captcha.jpg', param1=..., ...)This method is used to solve captchas that require rotating an object. It is primarily utilized for bypassing FunCaptcha and returns the rotation angle.
result = solver.rotate('path/to/captcha.jpg', param1=..., ...)The canvas method is used for captchas that require drawing a line around an object in an image. It returns a set of point coordinates for constructing a polygon.
result = solver.canvas('path/to/captcha.jpg', param1=..., ...)These methods allow manual captcha submission and answer polling. The send() method supports sending any captcha type. To specify the captcha type, you must manually set the method parameter, for example, method='recaptcha' for solving reCAPTCHA.
You can find the available values for the method parameter in the API documentation.
Example of manually solving a Normal captcha:
import time
. . . . .
id = solver.send(file='path/to/captcha.jpg')
time.sleep(20)
code = solver.get_result(id)Use this method to retrieve your account balance.
balance = solver.balance()Use this method to report whether a captcha answer was correct or incorrect.
solver.report(id, True) # captcha solved correctly
solver.report(id, False) # captcha solved incorrectlyIf an error occurs, the captcha solver throws an exception. Proper error handling is essential. We recommend using try except to manage exceptions.
A complete list of possible errors can be found in the API documentation.
try:
result = solver.text('If tomorrow is Saturday, what day is today?')
except ValidationException as e:
# invalid parameters passed
print(e)
except NetworkException as e:
# network error occurred
print(e)
except ApiException as e:
# api respond with error
print(e)
except TimeoutException as e:
# captcha is not solved so far
print(e)You can provide your proxy as an additional argument for the following methods: reCAPTCHA, FunCaptcha, GeeTest, GeeTest v4, KeyCaptcha, hCaptcha, Turnstile, Amazon WAF, and other captchas.
The proxy will be passed to the API to facilitate captcha solving.
We also offer our own proxies that you can use.
proxy={
'type': 'HTTPS',
'uri': 'login:password@IP_address:PORT'
}You can also perform asynchronous calls using asyncio, for example:
import asyncio
import concurrent.futures
from solvecaptcha import Solvecaptcha
API_KEY = "YOUR_API_KEY"
image = "data:image/png;base64,iVBORw0KGgoA..."
async def captchaSolver(image):
loop = asyncio.get_running_loop()
with concurrent.futures.ThreadPoolExecutor() as pool:
result = await loop.run_in_executor(pool, lambda: Solvecaptcha(API_KEY).normal(image))
return result
captcha_result = asyncio.run(captchaSolver(image))Examples of solving all supported captcha types can be found in the examples directory.
- Solve and bypass Google reCAPTCHA, hCaptcha, Image CAPTCHA, Cloudflare Challenge and any captcha in Selenium with captcha solver.
- Solve and bypass Google reCAPTCHA, hCaptcha, Arkose FunCaptcha, Cloudflare Turnstile, and any captcha in Puppeteer with captcha solver.
The code in this repository is licensed under the MIT License. For more details, see the LICENSE file.