Anti-Captcha Official Python Library

1.0.69 · active · verified Fri Apr 17

The `anticaptchaofficial` library is the official Python client for anti-captcha.com, providing an easy way to integrate various captcha solving services into your applications. It supports Image Captcha, reCAPTCHA v2/v3, hCaptcha, FunCaptcha, Geetest, and Square Net. The current version is 1.0.69, and it maintains an active release cadence with frequent updates.

Common errors

```
ModuleNotFoundError: No module named 'anticaptchaofficial'
```
cause The `anticaptchaofficial` library is not installed in your current Python environment.

fix Run `pip install anticaptchaofficial` to install the library.
```
Task finished with error: ERROR_KEY_DOES_NOT_EXIST
```
cause The API key provided to `solver.set_key()` is invalid, incorrectly formatted, or has expired.

fix Double-check your Anti-Captcha API key for correctness and ensure it's active. Prefer using environment variables for key management.
```
Task finished with error: ERROR_PAGEURL_OR_SITEKEY_EMPTY
```
cause For reCAPTCHA v2/v3 or hCaptcha, the `page_url` or `site_key` parameters were missing or empty in the `solve_and_return_solution` call.

fix Ensure that all required parameters for the specific solver you are using (e.g., `page_url`, `site_key` for reCAPTCHA) are correctly provided and not empty.
```
Task finished with error: ERROR_ZERO_BALANCE
```
cause Your anti-captcha.com account has insufficient funds to process the captcha task.

fix Log in to your anti-captcha.com account and top up your balance. Tasks will resume once funds are available.
```
Task finished with error: ERROR_IP_NOT_ALLOWED
```
cause Your API key is restricted to specific IP addresses, and the request is originating from an unallowed IP.

fix Check the API key settings on your anti-captcha.com dashboard and either allow the current IP address or disable IP restrictions if appropriate for your use case.

Warnings

gotcha Always handle the API key securely. Avoid hardcoding it directly in your source code. Use environment variables or a secure configuration management system.
Fix: Store your Anti-Captcha API key in an environment variable (e.g., `ANTI_CAPTCHA_API_KEY`) and retrieve it using `os.environ.get()`.
gotcha The `solve_and_return_solution` method returns `0` if the captcha task fails, with error details available in `solver.error_text` and `solver.error_code`. It's crucial to check for this `0` return and handle potential errors gracefully.
Fix: After calling `solve_and_return_solution`, always check if the result is `0`. If so, log or print `solver.error_text` to understand the failure reason.
gotcha Each captcha type (e.g., reCAPTCHA v2, hCaptcha, Image Captcha) requires a specific solver class and specific parameters for its `solve_and_return_solution` method. Using incorrect or missing parameters will lead to task failure.
Fix: Consult the official documentation or GitHub README for the exact parameters required by each specific `Solver` class you intend to use.
gotcha The library is synchronous. Calling `solve_and_return_solution` will block the current thread until the captcha is solved or fails. In web applications or highly concurrent environments, this can lead to performance issues.
Fix: For asynchronous applications, consider running captcha solving operations in a separate thread, process, or using an `asyncio.to_thread` wrapper if you are in an `asyncio` context.
gotcha Anti-captcha.com services require a sufficient account balance. If your balance is too low, tasks will fail with errors like `ERROR_ZERO_BALANCE`.
Fix: Monitor your account balance on anti-captcha.com and ensure it's sufficiently funded for your expected usage volume.

Install

pip install anticaptchaofficial Install stable version

Imports

RecaptchaV2Solver

from anticaptchaofficial.recaptchav2 import RecaptchaV2Solver

ImageCaptchaSolver

from anticaptchaofficial.imagecaptcha import ImageCaptchaSolver

HCaptchaSolver

from anticaptchaofficial.hcaptcha import HCaptchaSolver

Quickstart

This quickstart demonstrates how to solve a reCAPTCHA v2 challenge using the `RecaptchaV2Solver`. It highlights setting the API key, configuring verbose output, and providing the necessary `page_url` and `site_key`. The `solve_and_return_solution` method initiates the solving process and returns the captcha token or `0` on failure, with error details available in `solver.error_text`.

import os
from anticaptchaofficial.recaptchav2 import RecaptchaV2Solver

# It's recommended to store your API key in an environment variable.
api_key = os.environ.get('ANTI_CAPTCHA_API_KEY', 'YOUR_API_KEY_HERE')

if api_key == 'YOUR_API_KEY_HERE':
    print("WARNING: Please set the ANTI_CAPTCHA_API_KEY environment variable or replace 'YOUR_API_KEY_HERE' with your actual key.")
    # In a production application, you would typically exit or raise an error here.
    exit(1)

solver = RecaptchaV2Solver()
solver.set_key(api_key)
solver.set_verbose(1) # Optional: set to 1 for more verbose output during solving

# --- Required parameters for reCAPTCHA V2 ---
# The URL of the page where the captcha is located
page_url = "https://www.google.com/recaptcha/api2/demo" 
# The site key (data-sitekey) found in the HTML of the target page
site_key = "6Le-wvkSAAAAAPBMRTvw0Q4McdvzF00uzpXu7B0r" 

print(f"Attempting to solve reCAPTCHA V2 for {page_url} with site key {site_key}...")

# Solve the captcha
captcha_response = solver.solve_and_return_solution(page_url, site_key)

if captcha_response != 0:
    print(f"Captcha successfully solved! Response token: {captcha_response}")
    print("You can now submit this token to the target website's form.")
else:
    print(f"Failed to solve captcha. Error: {solver.error_text}")
    print(f"Error code: {solver.error_code}")

view raw JSON →