2captcha-python

Install the library using Pip to integrate the 2Captcha captcha-solving service into your Python projects.

pip3 install 2captcha-python

To use the library, initialize a TwoCaptcha instance with your API key. You can also use AsyncTwoCaptcha for asynchronous operations.

For advanced configuration, pass a dictionary of options to the constructor using keyword arguments.

from twocaptcha import TwoCaptcha

solver = TwoCaptcha('YOUR_API_KEY')

You can pass a proxy dictionary as an additional argument to several methods (including recaptcha, funcaptcha, geetest, turnstile, amazon waf, etc.) to have the proxy forwarded to the API.

The proxy dictionary should follow this format:

proxy={
    'type': 'HTTPS', # or other supported types
    'uri': 'login:password@IP_address:PORT'
}

The solver throws specific exceptions when errors occur. It is recommended to wrap calls in a try...except block to handle these cases:

• ValidationException: Invalid parameters were passed.
• NetworkException: A network error occurred.
• ApiException: The API responded with an error.
• TimeoutException: The captcha has not been solved within the expected timeframe.

try:
    result = solver.text('If tomorrow is Saturday, what day is today?')
except ValidationException as e:
    # invalid parameters passed
    print(e)
except NetworkException as e:
    # network error occurred
    print(e)
except ApiException as e:
    # api respond with error
    print(e)
except TimeoutException as e:
    # captcha is not solved so far
    print(e)

The AsyncTwoCaptcha class allows you to solve multiple captchas concurrently using asyncio.gather, which is significantly faster than solving them sequentially.

async def solve_multiple_captchas():
    solver = AsyncTwoCaptcha('YOUR_API_KEY')
    
    # Start all tasks simultaneously
    task1 = asyncio.create_task(solver.text('What color is the sky on a clear day?'))
    task2 = asyncio.create_task(solver.text('What is 2+2?'))
    task3 = asyncio.create_task(solver.text('Name of the planet we live on?'))
    
    # Wait for all tasks to complete
    results = await asyncio.gather(task1, task2, task3, return_exceptions=True)
    return results

# This completes much faster than solving captchas sequentially
results = asyncio.run(solve_multiple_captchas())

For backward compatibility, you can run the synchronous TwoCaptcha client within a thread pool using loop.run_in_executor.

import asyncio
import concurrent.futures
from twocaptcha import TwoCaptcha

API_KEY = "YOUR_API_KEY"
image = "data:image/png;base64,iVBORw0KGgoA..."

async def captchaSolver(image):
    loop = asyncio.get_running_loop()
    with concurrent.futures.ThreadPoolExecutor() as pool:
        result = await loop.run_in_executor(pool, lambda: TwoCaptcha(API_KEY).normal(image))
        return result

captcha_result = asyncio.run(captchaSolver(image))

Use solver.recaptcha() to solve reCAPTCHA. For v2, provide the sitekey and url. For v3, provide the sitekey, url, and set version='v3'.

# reCAPTCHA v2
result = solver.recaptcha(sitekey='6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-',
                          url='https://mysite.com/page/with/recaptcha',
                          param1=..., ...)

# reCAPTCHA v3
result = solver.recaptcha(sitekey='6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-',
                            url='https://mysite.com/page/with/recaptcha',
                            version='v3',
                            param1=..., ...)

Use solver.normal() for distorted text on images (supports local paths or URLs). Use solver.audio() for MP3 audio CAPTCHAs (requires lang parameter with values like 'en', 'ru', 'de', 'el', 'pt', 'fr'). Use solver.text() for CAPTCHAs that present a clear text question.

# Normal Captcha
result = solver.normal('path/to/captcha.jpg', param1=..., ...)
# OR
result = solver.normal('https://site-with-captcha.com/path/to/captcha.jpg', param1=..., ...)

# Audio Captcha
result = solver.audio('path/to/captcha.mp3', lang = 'en', param1=..., ...)

# Text Captcha
result = solver.text('If tomorrow is Saturday, what day is today?', param1=..., ...)

For custom captcha types not covered by dedicated methods, use send() to submit the captcha and get_result() to poll for the answer. When using send(), you must manually specify the method parameter (e.g., method='recaptcha') based on the 2Captcha API documentation.

import time

# Example for solving Normal captcha manually
id = solver.send(file='path/to/captcha.jpg')
time.sleep(20)

code = solver.get_result(id)

To perform non-blocking captcha solving, use the AsyncTwoCaptcha class. It supports all the same methods and parameters as the synchronous TwoCaptcha class but requires await for method calls.

import asyncio
from twocaptcha import AsyncTwoCaptcha

async def solve_captcha():
    solver = AsyncTwoCaptcha('YOUR_API_KEY')
    
    try:
        recaptcha_result = await solver.recaptcha(...)
        return recaptcha_result
    except Exception as e:
        print(e)
        return None

if __name__ == '__main__':
    result = asyncio.run(solve_captcha())