captchaai

Python Module for captchaAI API

The easiest way to quickly integrate captchaAI captcha solving service into your code to automate solving of any types of captcha.

• Python Module for captchaAI API
  • Installation
  • Configuration
    • captchaAI instance options
  • Solve captcha
    • Captcha options
    • Normal Captcha
    • ReCaptcha v2
    • ReCaptcha v3
    • hCaptcha
  • Other methods
    • send / getResult
    • balance
    • report
    • Error handling
    • Proxies
    • Async calls

Installation

This package can be installed with Pip:

pip3 install captchaAI

Configuration

captchaAI instance can be created like this:

from captchaAI import captchaAI

solver = captchaAI('YOUR_API_KEY')

Also there are few options that can be configured:

config = {
            'apiKey':           'YOUR_API_KEY',
            'defaultTimeout':    120,
            'recaptchaTimeout':  240,
            'pollingInterval':   10,
        }
solver = captchaAI(**config)

captchaAI instance options

Option	Default value	Description
defaultTimeout	120	Polling timeout in seconds for all captcha types except ReCaptcha. Defines how long the module tries to get the answer from res.php API endpoint
recaptchaTimeout	240	Polling timeout for ReCaptcha in seconds. Defines how long the module tries to get the answer from res.php API endpoint
pollingInterval	10	Interval in seconds between requests to res.php API endpoint, setting values less than 5 seconds is not recommended

Solve captcha

When you submit any image-based captcha use can provide additional options to help captchaAI workers to solve it properly.

Captcha options

Option	Default Value	Description
numeric	0	Defines if captcha contains numeric or other symbols [see more info in the API docs][post options]
minLength	0	minimal answer lenght
maxLength	0	maximum answer length
phrase	0	defines if the answer contains multiple words or not
caseSensitive	0	defines if the answer is case sensitive
calc	0	defines captcha requires calculation
lang	-	defines the captcha language, see the [list of supported languages]
hintImg	-	an image with hint shown to workers with the captcha
hintText	-	hint or task text shown to workers with the captcha

Below you can find basic examples for every captcha type. Check out examples directory to find more examples with all available options.

Normal Captcha

To bypass a normal captcha (distorted text on image) use the following method. This method also can be used to recognize any text on the image.

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

ReCaptcha v2

Use this method to solve ReCaptcha V2 and obtain a token to bypass the protection.

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

ReCaptcha v3

This method provides ReCaptcha V3 solver and returns a token.

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

hCaptcha

Use this method to solve hCaptcha challenge. Returns a token to bypass captcha.

result = solver.hcaptcha(sitekey='10000000-ffff-ffff-ffff-000000000001',
                            url='https://www.site.com/page/', 
                            param1=..., ...)

Other methods

send / getResult

These methods can be used for manual captcha submission and answer polling.

import time
. . . . . 


id = solver.send(file='path/to/captcha.jpg')
time.sleep(20)

code = solver.get_result(id)

balance

Use this method to get your account's balance

balance = solver.balance()

report

Use this method to report good or bad captcha answer.

solver.report(id, True) # captcha solved correctly
solver.report(id, False) # captcha solved incorrectly

Error handling

In case of an error, the captcha solver throws an exception. It's important to properly handle these cases. We recommend using try except to handle exceptions.

try:
    result = solver.recaptcha(sitekey=site_key,url=url)
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)

Proxies

You can pass your proxy as an additional argument for methods: recaptcha, funcaptcha and geetest. The proxy will be forwarded to the API to solve the captcha.

proxy={
    'type': 'HTTPS',
    'uri': 'login:password@IP_address:PORT'
}

Async calls

You can also make async calls with asyncio, for example:

import asyncio
import concurrent.futures
from captchaAI import captchaAI

captcha_result = await captchaSolver(image)

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