or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

audio-text-captchas.mdcloud-captchas.mdcore-solver.mdemerging-captchas.mdimage-captchas.mdindex.mdinteractive-captchas.mdspecialized-captchas.md
tile.json

tessl/pypi-2captcha-python

Python module for easy integration with 2Captcha API service to solve various types of captchas including reCAPTCHA, FunCaptcha, GeeTest, and many others

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/2captcha-python@1.5.x

To install, run

npx @tessl/cli install tessl/pypi-2captcha-python@1.5.0

index.mddocs/

2captcha-python

Python module for easy integration with the 2Captcha API service to solve various types of captchas including reCAPTCHA, FunCaptcha, GeeTest, hCaptcha, and many others. The library provides a comprehensive solution for automated captcha solving in web scraping, testing, and automation workflows.

Package Information

  • Package Name: 2captcha-python
  • Package Type: pypi
  • Language: Python
  • Installation: pip install 2captcha-python
  • Version: 1.5.1
  • License: MIT

Core Imports

from twocaptcha import TwoCaptcha

Import exceptions:

from twocaptcha import (
    SolverExceptions, 
    ValidationException, 
    NetworkException, 
    ApiException, 
    TimeoutException
)

Import low-level API client:

from twocaptcha import ApiClient

Basic Usage

from twocaptcha import TwoCaptcha

# Initialize the solver with your API key
solver = TwoCaptcha("YOUR_API_KEY")

# Solve a normal image captcha
result = solver.normal('/path/to/captcha.jpg')
print(f"Captcha solved: {result['code']}")

# Solve a reCAPTCHA v2
result = solver.recaptcha(
    sitekey='6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-',
    url='https://www.google.com/recaptcha/api2/demo'
)
print(f"reCAPTCHA token: {result['code']}")

# Check account balance
balance = solver.balance()
print(f"Account balance: ${balance}")

Architecture

The library is structured around two main classes:

  • TwoCaptcha: The primary high-level interface providing specialized methods for each captcha type
  • ApiClient: Low-level HTTP client for direct API communication

The TwoCaptcha class provides both automatic solving (submit and wait for result) and manual control (separate submit and polling). All captcha solving methods return a dictionary containing the captcha ID and solution code.

Capabilities

Core Solver API

Main TwoCaptcha class initialization, core solving methods, account management, and error handling. These provide the foundation for all captcha solving operations.

class TwoCaptcha:
    def __init__(self, apiKey, softId=4580, callback=None, 
                defaultTimeout=120, recaptchaTimeout=600, 
                pollingInterval=10, server='2captcha.com', 
                extendedResponse=None): ...
    
    def solve(self, timeout=0, polling_interval=0, **kwargs): ...
    def send(self, **kwargs): ...
    def get_result(self, id_): ...
    def balance(self): ...
    def report(self, id_, correct): ...

Core Solver API

Image Captchas

Methods for solving various types of image-based captchas including normal text captchas, grid-based selection captchas, coordinate-based click captchas, canvas drawing captchas, and image rotation captchas.

def normal(self, file, **kwargs): ...
def grid(self, file, **kwargs): ...
def coordinates(self, file, **kwargs): ...
def canvas(self, file, **kwargs): ...
def rotate(self, files, **kwargs): ...

Image Captchas

Interactive Captchas

Methods for solving interactive captcha challenges including reCAPTCHA v2/v3, FunCaptcha, GeeTest, hCaptcha, and other challenge-response systems that require browser interaction.

def recaptcha(self, sitekey, url, version='v2', 
             enterprise=0, **kwargs): ...
def funcaptcha(self, sitekey, url, **kwargs): ...
def geetest(self, gt, challenge, url, **kwargs): ...
def hcaptcha(self, sitekey, url, **kwargs): ...
def geetest_v4(self, captcha_id, url, **kwargs): ...

Interactive Captchas

Specialized Captchas

Methods for solving specialized captcha systems including KeyCaptcha, Capy, Lemin, ATB, and various other proprietary captcha solutions.

def keycaptcha(self, s_s_c_user_id, s_s_c_session_id,
              s_s_c_web_server_sign, s_s_c_web_server_sign2, 
              url, **kwargs): ...
def capy(self, sitekey, url, **kwargs): ...
def lemin(self, captcha_id, div_id, url, **kwargs): ...
def atb_captcha(self, app_id, api_server, url, **kwargs): ...

Specialized Captchas

Cloud Provider Captchas

Methods for solving captcha systems from major cloud providers including Cloudflare Turnstile, Amazon WAF, and other enterprise-grade protection systems.

def turnstile(self, sitekey, url, **kwargs): ...
def amazon_waf(self, sitekey, iv, context, url, **kwargs): ...
def friendly_captcha(self, sitekey, url, **kwargs): ...
def mtcaptcha(self, sitekey, url, **kwargs): ...

Cloud Provider Captchas

Emerging Captchas

Methods for solving newer and region-specific captcha systems including Tencent, CutCaptcha, DataDome, CyberSiARA, and Yandex Smart captchas.

def tencent(self, app_id, url, **kwargs): ...
def cutcaptcha(self, misery_key, apikey, url, **kwargs): ...
def datadome(self, captcha_url, pageurl, userAgent, proxy, **kwargs): ...
def cybersiara(self, master_url_id, pageurl, userAgent, **kwargs): ...
def yandex_smart(self, sitekey, url, **kwargs): ...

Emerging Captchas

Audio and Text Captchas

Methods for solving non-visual captcha challenges including audio captchas and text-based questions that require human reasoning or reading comprehension.

def audio(self, file, lang, **kwargs): ...
def text(self, text, **kwargs): ...

Audio and Text Captchas

Exception Types

class SolverExceptions(Exception):
    """Base exception class for all solver-related errors."""

class ValidationException(SolverExceptions):
    """Raised when input parameters fail validation."""

class NetworkException(SolverExceptions):
    """Raised when network communication fails."""

class ApiException(SolverExceptions):
    """Raised when the 2captcha API returns an error."""

class TimeoutException(SolverExceptions):
    """Raised when captcha solving exceeds timeout period."""

Low-Level API Client

class ApiClient:
    def __init__(self, post_url='2captcha.com'):
        """
        Initialize API client for direct 2captcha API communication.
        
        Parameters:
        - post_url: 2captcha server domain (default: '2captcha.com')
        """
    
    def in_(self, files={}, **kwargs):
        """
        Send POST request for captcha submission.
        
        Parameters:
        - files (dict): File attachments for image captchas
        - **kwargs: API request parameters
        
        Returns:
        str: API response string
        
        Raises:
        NetworkException: Network communication errors
        ApiException: API error responses
        """
    
    def res(self, **kwargs):
        """
        Send GET request for results and other operations.
        
        Parameters:
        - **kwargs: API request parameters
        
        Returns:
        str: API response string
        
        Raises:
        NetworkException: Network communication errors
        ApiException: API error responses
        """