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

cloud-captchas.mddocs/

Cloud Provider Captchas

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

Capabilities

Cloudflare Turnstile

Solves Cloudflare Turnstile captcha challenges, the modern replacement for reCAPTCHA.

def turnstile(self, sitekey, url, **kwargs):
    """
    Solve Cloudflare Turnstile captcha.
    
    Parameters:
    - sitekey (str): Value of sitekey parameter (required)
    - url (str): Full URL where Turnstile is located (required)
    - useragent (str): User agent string for browser simulation
    - action (str): Action parameter if specified on the page
    - data (str): Custom data parameter if present
    - pagedata (str): Additional page data parameter if present
    - 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 Turnstile response token
    """

Amazon WAF

Solves Amazon Web Application Firewall captcha challenges.

def amazon_waf(self, sitekey, iv, context, url, **kwargs):
    """
    Solve Amazon WAF captcha.
    
    Parameters:
    - sitekey (str): Value of sitekey parameter (required)
    - iv (str): Value of IV parameter (required)
    - context (str): Value of context parameter (required)
    - url (str): Full URL where Amazon WAF captcha is located (required)
    - challenge_script (str): URL of challenge script if different from default
    - captcha_script (str): URL of captcha script if different from default
    - 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 Amazon WAF solution
    """

MTCaptcha

Solves MTCaptcha challenges, a privacy-focused captcha solution.

def mtcaptcha(self, sitekey, url, **kwargs):
    """
    Solve MTCaptcha challenges.
    
    Parameters:
    - sitekey (str): Value of sitekey parameter (required)
    - url (str): Full URL where MTCaptcha 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 MTCaptcha response token
    """

Friendly Captcha

Solves Friendly Captcha challenges, which use proof-of-work instead of user interaction.

def friendly_captcha(self, sitekey, url, **kwargs):
    """
    Solve Friendly Captcha challenges.
    
    Parameters:
    - sitekey (str): Value of sitekey parameter (required)
    - url (str): Full URL where Friendly 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 Friendly Captcha solution
    """

Usage Examples

Cloudflare Turnstile

from twocaptcha import TwoCaptcha

solver = TwoCaptcha('your_api_key')

# Basic Turnstile
result = solver.turnstile(
    sitekey='0x1AAAAAAAAkg0s2VIWD34y',
    url='https://example.com/turnstile-form'
)
print(f"Turnstile token: {result['code']}")

# Turnstile with custom parameters
result = solver.turnstile(
    sitekey='turnstile_site_key',
    url='https://secure-site.com/form',
    useragent='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
    action='login',
    data='custom_data_value'
)
print(f"Token: {result['code']}")

# Turnstile with proxy
result = solver.turnstile(
    sitekey='site_key',
    url='https://example.com',
    proxy={'type': 'HTTPS', 'uri': 'user:pass@proxy.com:8080'}
)
print(f"Proxied token: {result['code']}")

Amazon WAF

from twocaptcha import TwoCaptcha

solver = TwoCaptcha('your_api_key')

# Solve Amazon WAF captcha
result = solver.amazon_waf(
    sitekey='waf_site_key',
    iv='initialization_vector',
    context='context_string',
    url='https://aws-protected-site.com/form'
)
print(f"Amazon WAF solution: {result['code']}")

# With custom script URLs
result = solver.amazon_waf(
    sitekey='site_key',
    iv='iv_value',
    context='context_value',
    url='https://example.com',
    challenge_script='https://custom-challenge-script.js',
    captcha_script='https://custom-captcha-script.js'
)
print(f"Solution: {result['code']}")

MTCaptcha

from twocaptcha import TwoCaptcha

solver = TwoCaptcha('your_api_key')

# Basic MTCaptcha
result = solver.mtcaptcha(
    sitekey='mtcaptcha_site_key',
    url='https://example.com/mt-form'
)
print(f"MTCaptcha token: {result['code']}")

# MTCaptcha with callback
result = solver.mtcaptcha(
    sitekey='site_key',
    url='https://secure-form.com',
    callback='https://yoursite.com/captcha-callback'
)
print(f"Token: {result['code']}")

Friendly Captcha

from twocaptcha import TwoCaptcha

solver = TwoCaptcha('your_api_key')

# Solve Friendly Captcha (proof-of-work)
result = solver.friendly_captcha(
    sitekey='friendly_site_key',
    url='https://example.com/friendly-form'
)
print(f"Friendly Captcha solution: {result['code']}")

# With proxy for geo-restricted sites
result = solver.friendly_captcha(
    sitekey='site_key',
    url='https://geo-restricted.com',
    proxy={'type': 'HTTPS', 'uri': 'user:pass@eu-proxy.com:8080'}
)
print(f"Solution: {result['code']}")

Integration with Selenium

from twocaptcha import TwoCaptcha
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

# Setup
solver = TwoCaptcha('your_api_key')
driver = webdriver.Chrome()

try:
    # Navigate to page with Turnstile
    driver.get('https://example.com/turnstile-protected-form')
    
    # Wait for Turnstile to load and get sitekey
    turnstile_iframe = WebDriverWait(driver, 10).until(
        EC.presence_of_element_located((By.CSS_SELECTOR, "iframe[src*='turnstile']"))
    )
    
    # Extract sitekey from page source
    page_source = driver.page_source
    # Parse sitekey from HTML (implementation depends on page structure)
    sitekey = "extracted_sitekey_value"
    
    # Solve Turnstile
    result = solver.turnstile(
        sitekey=sitekey,
        url=driver.current_url
    )
    
    # Inject solution into page
    driver.execute_script(f"""
        document.querySelector('[name="cf-turnstile-response"]').value = '{result['code']}';
    """)
    
    # Submit form
    submit_button = driver.find_element(By.CSS_SELECTOR, "input[type='submit']")
    submit_button.click()
    
    print(f"Form submitted with Turnstile token: {result['code']}")
    
finally:
    driver.quit()

Error Handling for Cloud Captchas

from twocaptcha import TwoCaptcha, ApiException, ValidationException

solver = TwoCaptcha('your_api_key')

try:
    result = solver.amazon_waf(
        sitekey='invalid_key',
        iv='',  # Empty required parameter
        context='context',
        url='https://example.com'
    )
except ValidationException as e:
    print(f"Validation error: {e}")
except ApiException as e:
    print(f"API error: {e}")

# Handle specific cloud captcha errors
try:
    result = solver.turnstile(
        sitekey='expired_sitekey',
        url='https://example.com'
    )
except ApiException as e:
    if 'INVALID_SITEKEY' in str(e):
        print("Sitekey is invalid or expired")
    elif 'TIMEOUT' in str(e):
        print("Captcha solving timed out")
    else:
        print(f"Other API error: {e}")

Performance Optimization

from twocaptcha import TwoCaptcha
import asyncio
import concurrent.futures

solver = TwoCaptcha('your_api_key')

def solve_turnstile(sitekey, url):
    """Solve single Turnstile captcha"""
    return solver.turnstile(sitekey=sitekey, url=url)

# Solve multiple captchas concurrently
sitekeys_and_urls = [
    ('sitekey1', 'https://site1.com'),
    ('sitekey2', 'https://site2.com'),
    ('sitekey3', 'https://site3.com')
]

with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
    futures = [
        executor.submit(solve_turnstile, sitekey, url) 
        for sitekey, url in sitekeys_and_urls
    ]
    
    results = []
    for future in concurrent.futures.as_completed(futures):
        try:
            result = future.result()
            results.append(result['code'])
            print(f"Solved: {result['code']}")
        except Exception as e:
            print(f"Error: {e}")

print(f"Total solved: {len(results)}")

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