Join And Get Free Trial!

python captcha solver

Python is a high-level, interpreted programming language. It is known for its simplicity and readability. It is a versatile language that can be used for web development, data analysis, artificial intelligence, and more.

Integrate our Python captcha solver package to automatically solve CAPTCHA on any website.

Easy integration with the API of captcha solving service to bypass reCAPTCHA and solve any other CAPTCHA

Installation

Install NextCaptcha Python SDK with pip or manually

PIP

To install the NextCaptcha Python SDK, you can use pip (recommended) or install it manually.

1. Install with pip (Recommended)#

If the NextCaptcha SDK is published on PyPI, you can install it with: 
pip install nextcaptcha-python
Or, if it's hosted on GitHub: 
pip install git+https://github.com/nextcaptcha/nextcaptcha-python.git

2. Manual Installation#

If you have the SDK as a local file or ZIP archive, follow these steps:

Step 1: Download the SDK#

  • Clone the repository: 
git clone https://github.com/nextcaptcha/nextcaptcha-python.git
cd nextcaptcha-python
OR
  • Download the ZIP from GitHub, extract it, and navigate to the folder.

Install Locally.#

pip install .
Or, if the SDK is not structured as a package: 
python setup.py install

Verify Installation#

Run Python and check if the package imports correctly: 
import nextcaptcha
print(nextcaptcha.__version__)
If you encounter any issues, ensure you have the required dependencies installed with: 
pip install -r requirements.txt

Configuration

Configure the NextCaptcha Python SDK with necessary parameters

Configuration of Solver SDK

To configure the NextCaptcha Python SDK, you'll need to set up the following parameters:
  • client_key: Your API key from NextCaptcha
  • soft_id: Your software ID (optional)
  • callback_url: The URL for receiving responses asynchronously (if using callback mode)
  • open_log: Enable logging for debugging

** Configuration Example**#

Here’s how you can set up and use the NextCaptcha Python SDK: 
from nextcaptcha import NextCaptchaAPI
 
# Configuration settings
config = {
    "client_key": "your_client_key_here",  # Replace with your NextCaptcha API key
    "soft_id": 12345,  # Your software ID (optional, replace if required)
    "callback_url": "https://your-callback-url.com",  # Callback URL (optional)
    "open_log": True  # Enable logging for debugging
}
 
# Initialize the NextCaptcha client
solver = NextCaptchaAPI(**config)
 
# Test request (example: solving a reCAPTCHA)
task = {
    "type": "ReCaptchaV2TaskProxyless",
    "websiteURL": "https://example.com",
    "websiteKey": "your_recaptcha_site_key"
}
 
# Send the task and get the result
try:
    task_id = solver.create_task(task)
    result = solver.get_result(task_id)
    print("Captcha solution:", result)
except Exception as e:
    print("Error:", str(e))

Explanation of Parameters#

ParameterDescription
client_keyYour NextCaptcha API key (required)
soft_idYour software ID (optional)
callback_urlA URL where the results will be sent (optional, only for async tasks)
open_logIf `True`, enables logging for debugging

notes#

  • If using callback mode, the solution will be sent to the `callback_url`, so you don't need to fetch results manually.
  • If `open_log=True`, logs will be printed to help with debugging.
  • Make sure to replace placeholders (`your_client_key_here`, etc.) with your actual credentials.

Solve CAPTCHA

Solve reCAPTCHA v2/v3/Enterprise via Token-based method

To solve reCAPTCHA v2, v3, Enterprise, or the mobile version using NextCaptcha's Token-based method, follow these steps:

1. Solve reCAPTCHA via Token-Based Method#

Use the Token-based approach to get the `g-recaptcha-response` token.

Solve reCAPTCHA v2 with Token base method#

 
# {props.t('solve6')}
 
result = api.recaptchav2(website_url="https://example.com", website_key="SITE_KEY")

Solve reCAPTCHA v2 Enterprise with Token base method#

# {props.t('solve6')}
result = api.recaptchav2enterprise(website_url="https://example.com", website_key="SITE_KEY")

Solve reCAPTCHA v2 Enterprise with high score Token base method#

result = api.recaptchav2hs_enterprise(website_url="https://example.com", website_key="SITE_KEY")

Solve reCAPTCHA v3 or v3 Enterprise with Token base method#

result = api.recaptchav3(website_url="https://example.com", website_key="SITE_KEY")

Solve reCAPTCHA v3 or v3 Enterprise with high score Token base method#

result = api.recaptchav3hs(website_url="https://example.com", website_key="SITE_KEY")

Solve reCAPTCHA Mobile with Token base method#

result = api.recaptcha_mobile(app_key="APP_KEY", app_package_name="com.example.app", app_action="APP_ACTION", app_device="ios")

3. Use the Token#

After receiving the `g-recaptcha-response` token, inject it into the website’s form and submit it. 
<input type="hidden" name="g-recaptcha-response" value="your_token_here" />

Explanation of Parameters#

ParameterDescription
website_urlThe URL of the website where the reCAPTCHA is located
website_keyThe sitekey of the reCAPTCHA
page_actionThe action parameter to use for the reCAPTCHA
api_domainThe domain of the reCAPTCHA API if different from the default
website_infoDetailed reCAPTCHA config about a target website the

Key Notes#

✅ Supports reCAPTCHA v2, v3, Enterprise, and Mobile

✅ Proxyless mode is available (use a proxy if the site requires specific IPs)

✅ Token-based method allows seamless captcha bypassing.

Other methods

To check your NextCaptcha account balance, use the following method:

Get Balance Example#

# Get account balance
balance = api.get_balance()
print(f"Account balance: {balance}")

Key Notes#

✅ Retrieves your available balance in USD.

✅ Ensure your API key is valid to get the correct balance.

Error handling

If an error occurs while solving a captcha, the SDK will return a dictionary containing the error information. You can check the status field to determine if the request was successful. If the status is "ready", the captcha has been successfully solved and the solution will be provided in the solution field. If the status is "failed", the error field will contain a description of the error.
IdCodeDescription
0-no error occurred
1ERROR_KEY_DOES_NOT_EXISTYour API key is incorrect, please make sure you have set it up correctly and copy it from client or developer mode in Control Panel
10ERROR_ZERO_BALANCEYour account balance is zero
11ERROR_IP_NOT_ALLOWEDThe request was made from an IP address that is not in your trusted IP list
12ERROR_CAPTCHA_UNSOLVABLEThe captcha cannot be solved normally. It may encounter a proxy, or the solution fails for various network reasons. In general, you can try again.
14ERROR_NO_SUCH_METHODA method that does not exist in the API was requested
15ERROR_IMAGE_TYPE_NOT_SUPPORTEDThe image cannot be processed because the image format or size is incorrect, or the image is corrupted. Please check the image in your request
16ERROR_NO_SUCH_CAPCHA_IDThe Captcha ID you provided is incorrect
21ERROR_IP_BLOCKEDYour IP address has been banned due to inappropriate use of the API
22ERROR_TASK_ABSENTYou did not include the task attribute in the createTask method call
23ERROR_TASK_NOT_SUPPORTEDThe task attribute in your createTask method call contains a task type that is not support by Our API, or the type attribute is incorrect.
31ERROR_RECAPTCHA_INVALID_SITEKEYThe reCAPTCHA sitekey value you provided is invalid
55ERROR_ACCOUNT_SUSPENDEDYour account has been suspended due to improper use of API. Please Connect Via Telegram support team to resolve this issue
130ERROR_BAD_PROXYThe proxy parameters are incorrect or the connection cannot be established through the proxy
110ERROR_BAD_PARAMETERSA required captcha parameter is missing from your request, or the parameter format is incorrect. Please ensure that your request payload format is appropriate for the selected task type
500ERROR_UNKNOWNUnknown error. It may be an unexpected error in the system. You can contact the administrator who sent the error to solve the problem.