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.
To get started quickly, check out the Captcha Solver API documentation.
Need help integrating with your Python app or automation tools? Open an issue or fork this repo to contribute.
This package can be installed using Pip:
pip3 install solvecaptcha-python
or You can install this package directly from GitHub using pip:
pip install git+https://github.com/solvercaptcha/solvecaptcha-python.git
An 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
callbackis defined for theSolvecaptchainstance, 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=..., ...)
Use the following method to solve hCaptcha and retrieve a token for bypassing the protection.
result = solver.hcaptcha(sitekey='bf8ccfbf-6a05-45f6-982a-7a7964c2f50c',
url='https://portalunico.siscomex.gov.br',
invisible=0,
domain='hcaptcha.com',
# proxy={
# 'type': 'HTTPS',
# 'uri': 'login:password@IP_address:PORT'
# }
)
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 incorrectly
If 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.
We also have a separate repository where you can find examples of captcha solving using the Selenium \ seleniumbase library.
The code in this repository is licensed under the MIT License. For more details, see the LICENSE file.
FAQs
Python module for easy integration with solvecaptcha.com API
We found that solvecaptcha-python demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Malicious npm packages targeting React, Vue, Vite, Node.js, and Quill remained undetected for two years while deploying destructive payloads.
Security News
Open source maintainers are urging GitHub to let them block Copilot from submitting AI-generated issues and pull requests to their repositories.
Research
Security News
Malicious Koishi plugin silently exfiltrates messages with hex strings to a hardcoded QQ account, exposing secrets in chatbots across platforms.