2Captcha Python Client

Warnings

• breaking Version 2.0.0 introduced asynchronous API support, requiring the use of `AsyncTwoCaptcha` and `await` for async operations. While synchronous methods (`TwoCaptcha`) are still available, users transitioning to async workflows must update their code accordingly.
  Fix: For asynchronous operations, replace `from twocaptcha import TwoCaptcha` with `from twocaptcha import AsyncTwoCaptcha` and ensure all API calls are `await`ed within an `async` function. Synchronous code remains compatible with `TwoCaptcha`.
• deprecated The underlying 2Captcha API v1 is deprecated. All new features and improvements are being added exclusively to API v2. While API v1 remains supported for compatibility, migrating to API v2 (which `2captcha-python` v2.x utilizes) is highly recommended to access the latest functionalities and ensure future compatibility.
  Fix: Upgrade to `2captcha-python` version 2.x or later. Review the documentation for specific captcha types as API parameter changes might exist between v1 and v2.
• gotcha Using the incorrect captcha type or providing wrong parameters for a specific captcha will lead to failed solutions and wasted funds. 2Captcha supports numerous captcha types, each requiring a specific API method and set of parameters.
  Fix: Always identify the exact captcha type on the target website (e.g., reCAPTCHA V2, hCaptcha, image-to-text) and use the corresponding method in the `TwoCaptcha` or `AsyncTwoCaptcha` client (e.g., `solver.recaptcha`, `solver.hcaptcha`, `solver.normal`). Carefully consult the 2Captcha API documentation for required parameters.
• gotcha Inadequate error handling can lead to silent failures or unhandled exceptions. The library throws specific exceptions (`ValidationException`, `NetworkException`, `ApiException`) for different error scenarios from the API or network issues.
  Fix: Always wrap your API calls in `try...except` blocks to catch and handle `ValidationException`, `NetworkException`, and `ApiException`. This allows for robust error recovery, logging, and prevents script crashes.
• gotcha Poor account balance management and inefficient polling logic can quickly drain your budget or lead to rate limiting. Polling for results too frequently (e.g., every 100ms) can trigger `MAX_USER_TURN` errors, while not monitoring your balance can lead to service interruptions.
  Fix: Check your 2Captcha account balance regularly. Implement reasonable polling intervals (e.g., 5 seconds as suggested by 2Captcha) for `get_result` calls. Avoid aggressive retries of captchas that consistently fail; review parameters or the captcha itself.
• gotcha Hardcoding your 2Captcha API key directly in your scripts poses a security risk. If your code is exposed, your API key can be compromised.
  Fix: Always use environment variables (e.g., `os.environ.get('TWO_CAPTCHA_API_KEY')`) or a secure configuration management system to store and access your API key. Never commit API keys to version control.

Install

• pip install 2captcha-python Install with pip

Imports

• TwoCaptcha

  from twocaptcha import TwoCaptcha

  For synchronous API calls.
• AsyncTwoCaptcha

  from twocaptcha import AsyncTwoCaptcha

  For asynchronous API calls (introduced in v2.0.0).

Quickstart

This quickstart demonstrates how to solve a basic image-to-text captcha using the synchronous `TwoCaptcha` client. It emphasizes loading the API key from environment variables for security and includes comprehensive error handling for common API and network issues. Replace `'path/to/captcha.jpg'` with your captcha image file path or URL for a runnable example.

import os
from twocaptcha import TwoCaptcha
from twocaptcha.solver import ValidationException, NetworkException, ApiException

# Best practice: Load API key from environment variables
API_KEY = os.environ.get('TWO_CAPTCHA_API_KEY', 'YOUR_2CAPTCHA_API_KEY')

solver = TwoCaptcha(API_KEY)

try:
    # Example: Solving a normal image-to-text captcha
    # Replace 'path/to/captcha.jpg' with your captcha image file path or URL
    # You can also pass base64 encoded image data
    result = solver.normal('path/to/captcha.jpg')
    print(f"Captcha solved: {result['code']}")
    # The 'id' field can be used to report incorrect solutions later
    # print(f"Captcha ID: {result['id']}")
except ValidationException as e:
    print(f"Validation error: {e}")
except NetworkException as e:
    print(f"Network error: {e}")
except ApiException as e:
    print(f"API error: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")