{"id":9464,"library":"anticaptchaofficial","title":"Anti-Captcha Official Python Library","description":"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.","status":"active","version":"1.0.69","language":"en","source_language":"en","source_url":"https://github.com/anti-captcha/anticaptcha-python","tags":["captcha","automation","anti-captcha","api-client","recaptcha","hcaptcha"],"install":[{"cmd":"pip install anticaptchaofficial","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"RecaptchaV2Solver","correct":"from anticaptchaofficial.recaptchav2 import RecaptchaV2Solver"},{"symbol":"ImageCaptchaSolver","correct":"from anticaptchaofficial.imagecaptcha import ImageCaptchaSolver"},{"symbol":"HCaptchaSolver","correct":"from anticaptchaofficial.hcaptcha import HCaptchaSolver"}],"quickstart":{"code":"import os\nfrom anticaptchaofficial.recaptchav2 import RecaptchaV2Solver\n\n# It's recommended to store your API key in an environment variable.\napi_key = os.environ.get('ANTI_CAPTCHA_API_KEY', 'YOUR_API_KEY_HERE')\n\nif api_key == 'YOUR_API_KEY_HERE':\n    print(\"WARNING: Please set the ANTI_CAPTCHA_API_KEY environment variable or replace 'YOUR_API_KEY_HERE' with your actual key.\")\n    # In a production application, you would typically exit or raise an error here.\n    exit(1)\n\nsolver = RecaptchaV2Solver()\nsolver.set_key(api_key)\nsolver.set_verbose(1) # Optional: set to 1 for more verbose output during solving\n\n# --- Required parameters for reCAPTCHA V2 ---\n# The URL of the page where the captcha is located\npage_url = \"https://www.google.com/recaptcha/api2/demo\" \n# The site key (data-sitekey) found in the HTML of the target page\nsite_key = \"6Le-wvkSAAAAAPBMRTvw0Q4McdvzF00uzpXu7B0r\" \n\nprint(f\"Attempting to solve reCAPTCHA V2 for {page_url} with site key {site_key}...\")\n\n# Solve the captcha\ncaptcha_response = solver.solve_and_return_solution(page_url, site_key)\n\nif captcha_response != 0:\n    print(f\"Captcha successfully solved! Response token: {captcha_response}\")\n    print(\"You can now submit this token to the target website's form.\")\nelse:\n    print(f\"Failed to solve captcha. Error: {solver.error_text}\")\n    print(f\"Error code: {solver.error_code}\")\n","lang":"python","description":"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`."},"warnings":[{"fix":"Store your Anti-Captcha API key in an environment variable (e.g., `ANTI_CAPTCHA_API_KEY`) and retrieve it using `os.environ.get()`.","message":"Always handle the API key securely. Avoid hardcoding it directly in your source code. Use environment variables or a secure configuration management system.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the official documentation or GitHub README for the exact parameters required by each specific `Solver` class you intend to use.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor your account balance on anti-captcha.com and ensure it's sufficiently funded for your expected usage volume.","message":"Anti-captcha.com services require a sufficient account balance. If your balance is too low, tasks will fail with errors like `ERROR_ZERO_BALANCE`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install anticaptchaofficial` to install the library.","cause":"The `anticaptchaofficial` library is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'anticaptchaofficial'"},{"fix":"Double-check your Anti-Captcha API key for correctness and ensure it's active. Prefer using environment variables for key management.","cause":"The API key provided to `solver.set_key()` is invalid, incorrectly formatted, or has expired.","error":"Task finished with error: ERROR_KEY_DOES_NOT_EXIST"},{"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.","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.","error":"Task finished with error: ERROR_PAGEURL_OR_SITEKEY_EMPTY"},{"fix":"Log in to your anti-captcha.com account and top up your balance. Tasks will resume once funds are available.","cause":"Your anti-captcha.com account has insufficient funds to process the captcha task.","error":"Task finished with error: ERROR_ZERO_BALANCE"},{"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.","cause":"Your API key is restricted to specific IP addresses, and the request is originating from an unallowed IP.","error":"Task finished with error: ERROR_IP_NOT_ALLOWED"}]}