CtrlK
BlogDocsLog inGet started
Tessl Logo

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

emerging-captchas.mddocs/

Emerging Captchas

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

Capabilities

Tencent Captcha

Solves Tencent captcha challenges commonly used in Chinese websites and applications.

def tencent(self, app_id, url, **kwargs):
    """
    Solve Tencent captcha challenges.
    
    Parameters:
    - app_id (str): Tencent application ID (required)
    - url (str): Full URL where Tencent captcha is located (required)
    - softId (int): Software developer ID
    - callback (str): Pingback URL for result notification
    - proxy (dict): Proxy configuration {'type': 'HTTPS', 'uri': 'login:pass@ip:port'}
    
    Returns:
    dict: {'captchaId': str, 'code': str} - code contains Tencent captcha solution
    """

CutCaptcha

Solves CutCaptcha challenges that involve sliding or fitting puzzle pieces.

def cutcaptcha(self, misery_key, apikey, url, **kwargs):
    """
    Solve CutCaptcha challenges.
    
    Parameters:
    - misery_key (str): CutCaptcha misery key parameter (required)
    - apikey (str): CutCaptcha API key parameter (required)
    - url (str): Full URL where CutCaptcha is located (required)
    - softId (int): Software developer ID
    - callback (str): Pingback URL for result notification
    - proxy (dict): Proxy configuration {'type': 'HTTPS', 'uri': 'login:pass@ip:port'}
    
    Returns:
    dict: {'captchaId': str, 'code': str} - code contains CutCaptcha solution
    """

DataDome Captcha

Solves DataDome bot protection captcha challenges.

def datadome(self, captcha_url, pageurl, userAgent, proxy, **kwargs):
    """
    Solve DataDome Captcha challenges.
    
    Parameters:
    - captcha_url (str): URL to the DataDome captcha page (required)
    - pageurl (str): URL of the original page being protected (required)
    - userAgent (str): User agent string that triggered the captcha (required)
    - proxy (dict): Proxy configuration (required) {'type': 'HTTPS', 'uri': 'login:pass@ip:port'}
    
    Returns:
    dict: {'captchaId': str, 'code': str} - code contains DataDome solution cookie
    """

CyberSiARA

Solves CyberSiARA captcha challenges.

def cybersiara(self, master_url_id, pageurl, userAgent, **kwargs):
    """
    Solve CyberSiARA captcha challenges.
    
    Parameters:
    - master_url_id (str): CyberSiARA master URL ID (required)
    - pageurl (str): URL of the page with CyberSiARA captcha (required)
    - userAgent (str): User agent string for browser simulation (required)
    - proxy (dict): Proxy configuration {'type': 'HTTPS', 'uri': 'login:pass@ip:port'}
    
    Returns:
    dict: {'captchaId': str, 'code': str} - code contains CyberSiARA solution
    """

Yandex Smart Captcha

Solves Yandex Smart Captcha challenges used on Russian websites.

def yandex_smart(self, sitekey, url, **kwargs):
    """
    Solve Yandex Smart Captcha challenges.
    
    Parameters:
    - sitekey (str): Yandex Smart Captcha sitekey (required)
    - url (str): Full URL where Yandex captcha is located (required)
    - softId (int): Software developer ID
    - callback (str): Pingback URL for result notification
    - proxy (dict): Proxy configuration {'type': 'HTTPS', 'uri': 'login:pass@ip:port'}
    - userAgent (str): User agent string for browser simulation
    
    Returns:
    dict: {'captchaId': str, 'code': str} - code contains Yandex Smart Captcha token
    """

Usage Examples

Tencent Captcha

from twocaptcha import TwoCaptcha

solver = TwoCaptcha('your_api_key')

# Solve Tencent captcha
result = solver.tencent(
    app_id='tencent_app_id',
    url='https://chinese-site.com/login'
)
print(f"Tencent solution: {result['code']}")

# With proxy for geographic access
result = solver.tencent(
    app_id='app_123',
    url='https://qq.com/form',
    proxy={'type': 'HTTPS', 'uri': 'user:pass@china-proxy.com:8080'}
)
print(f"Solution: {result['code']}")

CutCaptcha

from twocaptcha import TwoCaptcha

solver = TwoCaptcha('your_api_key')

# Solve CutCaptcha puzzle
result = solver.cutcaptcha(
    misery_key='cutcaptcha_misery_key',
    apikey='cutcaptcha_api_key',
    url='https://example.com/cutcaptcha-form'
)
print(f"CutCaptcha solution: {result['code']}")

# With proxy support
result = solver.cutcaptcha(
    misery_key='misery_123',
    apikey='api_456',
    url='https://secure-site.com',
    proxy={'type': 'HTTPS', 'uri': 'proxy_user:proxy_pass@proxy.com:3128'}
)
print(f"Solution: {result['code']}")

DataDome Captcha

from twocaptcha import TwoCaptcha

solver = TwoCaptcha('your_api_key')

# Solve DataDome captcha (requires all parameters)
result = solver.datadome(
    captcha_url='https://geo.captcha-delivery.com/captcha/?initialCid=...',
    pageurl='https://protected-site.com/page',
    userAgent='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
    proxy={'type': 'HTTPS', 'uri': 'user:pass@proxy.com:8080'}
)
print(f"DataDome cookie: {result['code']}")

CyberSiARA

from twocaptcha import TwoCaptcha

solver = TwoCaptcha('your_api_key')

# Solve CyberSiARA captcha
result = solver.cybersiara(
    master_url_id='cybersiara_master_id',
    pageurl='https://example.com/cybersiara-page',
    userAgent='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'
)
print(f"CyberSiARA solution: {result['code']}")

# With proxy
result = solver.cybersiara(
    master_url_id='master_123',
    pageurl='https://protected.com',
    userAgent='Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
    proxy={'type': 'HTTPS', 'uri': 'user:pass@proxy.com:8080'}
)
print(f"Solution: {result['code']}")

Yandex Smart Captcha

from twocaptcha import TwoCaptcha

solver = TwoCaptcha('your_api_key')

# Solve Yandex Smart Captcha
result = solver.yandex_smart(
    sitekey='yandex_sitekey',
    url='https://yandex.ru/form'
)
print(f"Yandex token: {result['code']}")

# With custom user agent and proxy
result = solver.yandex_smart(
    sitekey='sitekey_value',
    url='https://russian-site.ru',
    userAgent='Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:91.0) Gecko/20100101 Firefox/91.0',
    proxy={'type': 'HTTPS', 'uri': 'user:pass@russia-proxy.com:8080'}
)
print(f"Token: {result['code']}")

Real-World Integration Example

from twocaptcha import TwoCaptcha
import requests
import json

solver = TwoCaptcha('your_api_key')

def solve_datadome_protected_site():
    """Example of solving DataDome protection on a real site"""
    
    # Step 1: Make initial request that triggers DataDome
    session = requests.Session()
    session.headers.update({
        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'
    })
    
    try:
        response = session.get('https://protected-site.com/data')
        
        # Check if DataDome captcha is triggered
        if 'geo.captcha-delivery.com' in response.url:
            print("DataDome captcha detected")
            
            # Extract captcha URL
            captcha_url = response.url
            original_url = 'https://protected-site.com/data'
            
            # Solve captcha
            result = solver.datadome(
                captcha_url=captcha_url,
                pageurl=original_url,
                userAgent=session.headers['User-Agent'],
                proxy={'type': 'HTTPS', 'uri': 'user:pass@proxy.com:8080'}
            )
            
            # Use the solution cookie
            datadome_cookie = result['code']
            session.cookies.set('datadome', datadome_cookie)
            
            # Retry original request
            response = session.get(original_url)
            print(f"Request successful: {response.status_code}")
            return response.json()
            
    except Exception as e:
        print(f"Error: {e}")
        return None

# Usage
data = solve_datadome_protected_site()
if data:
    print("Successfully bypassed DataDome protection")

Error Handling for Emerging Captchas

from twocaptcha import TwoCaptcha, ValidationException, ApiException

solver = TwoCaptcha('your_api_key')

# Handle validation errors for required parameters
try:
    result = solver.datadome(
        captcha_url='',  # Empty required parameter
        pageurl='https://example.com',
        userAgent='Mozilla/5.0...',
        proxy={'type': 'HTTPS', 'uri': 'proxy:8080'}
    )
except ValidationException as e:
    print(f"Missing required parameter: {e}")

# Handle regional captcha errors
try:
    result = solver.tencent(
        app_id='invalid_app_id',
        url='https://chinese-site.com'
    )
except ApiException as e:
    if 'INVALID_APP_ID' in str(e):
        print("Tencent app ID is invalid")
    elif 'REGION_BLOCKED' in str(e):
        print("Service blocked in this region, try using a proxy")
    else:
        print(f"API error: {e}")

# Handle geographic restrictions
try:
    result = solver.yandex_smart(
        sitekey='yandex_key',
        url='https://yandex.ru/form'
    )
except ApiException as e:
    if 'GEO_RESTRICTED' in str(e):
        print("Yandex captcha requires Russian IP address")
        # Retry with Russian proxy
        result = solver.yandex_smart(
            sitekey='yandex_key',
            url='https://yandex.ru/form',
            proxy={'type': 'HTTPS', 'uri': 'user:pass@russian-proxy.com:8080'}
        )
        print(f"Solved with proxy: {result['code']}")

Performance Tips for Emerging Captchas

from twocaptcha import TwoCaptcha
import time

solver = TwoCaptcha('your_api_key')

# Regional captchas may take longer, increase timeouts
solver_extended = TwoCaptcha(
    'your_api_key',
    defaultTimeout=300,  # 5 minutes for regional captchas
    pollingInterval=15   # Check less frequently
)

# Batch solving for multiple regions
regional_captchas = [
    ('tencent', {'app_id': 'app1', 'url': 'https://site1.cn'}),
    ('yandex_smart', {'sitekey': 'key1', 'url': 'https://site1.ru'}),
    ('cutcaptcha', {'misery_key': 'mk1', 'apikey': 'ak1', 'url': 'https://site1.com'})
]

for captcha_type, params in regional_captchas:
    try:
        method = getattr(solver_extended, captcha_type)
        result = method(**params)
        print(f"{captcha_type} solved: {result['code']}")
    except Exception as e:
        print(f"Failed {captcha_type}: {e}")
        continue

Install with Tessl CLI

npx tessl i tessl/pypi-2captcha-python

docs

audio-text-captchas.md

cloud-captchas.md

core-solver.md

emerging-captchas.md

image-captchas.md

index.md

interactive-captchas.md

specialized-captchas.md

tile.json