Unicaps
Unicaps is a unified Python API for CAPTCHA solving services.
⚠ PLEASE NOTE
⚠ A solving service API key is required to use this package!
⚠ The list of the supported services you can find in the table below.
Key Features
- A unified Python interface that is independent of the service used
- Uses native service protocol/endpoints (eg, no needs in patching hosts file)
- Has both synchronous and asynchronous client
- Supports 10 types of CAPTCHAs
- Supports 7 CAPTCHA solving services
- Written Pythonic way and is intended for humans
Installation
pip install -U unicaps
Simple Usage Example
>>> from unicaps import CaptchaSolver, CaptchaSolvingService
>>> solver = CaptchaSolver(CaptchaSolvingService.TWOCAPTCHA, api_key="<PLACE_YOUR_API_KEY_HERE>")
>>> solver.get_balance()
2.84161
>>> solved = solver.solve_image_captcha(open("captcha.jpg", "rb"), is_phrase=False, is_case_sensitive=True)
>>> solved.solution.text
'w93Bx'
>>> solved.cost
0.00078
>>> solved.report_good()
True
Asynchronous Example
import asyncio
from pathlib import Path
from unicaps import AsyncCaptchaSolver, CaptchaSolvingService
API_KEY = '<PLACE_YOUR_API_KEY_HERE>'
async def main():
async with AsyncCaptchaSolver(CaptchaSolvingService.TWOCAPTCHA, API_KEY) as solver:
solved = await solver.solve_image_captcha(
Path("captcha.jpg"),
is_phrase=False,
is_case_sensitive=True
)
print(f'CAPTCHA text: {solved.solution.text}')
await solved.report_good()
if __name__ == '__main__':
asyncio.run(main())
Supported CAPTCHAs / Services
Image CAPTCHA
Text CAPTCHA
What is this?
Text Captcha is a type of captcha that is represented as text and doesn't contain images. Usually you have to answer a question to pass the verification.
For example: "If tomorrow is Saturday, what day is today?".
reCAPTCHA v2
1 Support of solving reCAPTCHA on Google services (e.g. Google Search)
2 Support of solving via proxy server
3 Support of passing custom cookies
4 Support of passing custom User-Agent header
reCAPTCHA v3
FunCaptcha (Arkose Labs)
KeyCAPTCHA
Geetest
Geetest v4
hCaptcha
Capy Puzzle
Supported Proxy types
How to...
Common
Get balance
from unicaps import CaptchaSolver, CaptchaSolvingService
# init captcha solver
with CaptchaSolver(CaptchaSolvingService.ANTI_CAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
balance = solver.get_balance()
Get service status (is the service is up?)
from unicaps import CaptchaSolver, CaptchaSolvingService
# init captcha solver
with CaptchaSolver(CaptchaSolvingService.ANTI_CAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
# get status of the service (True - everything is Okay, False - probably the service is down)
status = solver.get_status()
Get technical details after solving
from unicaps import CaptchaSolver, CaptchaSolvingService
# init captcha solver and solve the captcha
with CaptchaSolver(CaptchaSolvingService.ANTI_CAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
solved = solver.solve_...(...)
# get cost of the solving
cost = solved.cost
# get cookies (if any)
cookies = solved.cookies
# report good captcha
solved.report_good()
# report bad captcha
solved.report_bad()
# get solving start time
start_time = solved.start_time
# get solving end time
end_time = solved.end_time
CAPTCHAs
Solve Image CAPTCHA
import pathlib
from unicaps import CaptchaSolver, CaptchaSolvingService
from unicaps.common import CaptchaCharType, CaptchaAlphabet
# image file: it can be a Path, file-object or bytes.
image_file = pathlib.Path(r'/tmp/captcha.png')
# init captcha solver
with CaptchaSolver(CaptchaSolvingService.TWOCAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
# solve CAPTCHA
solved = solver.solve_image_captcha(
image=image_file,
char_type=CaptchaCharType.ALPHA, # optional
is_phrase=False, # optional
is_case_sensitive=True, # optional
is_math=False, # optional
min_len=4, # optional
max_len=6, # optional
alphabet=CaptchaAlphabet.LATIN, # optional
comment='Type RED letters only' # optional
)
# get CAPTCHA text
token = solved.solution.text
Solve reCAPTCHA v2
from unicaps import CaptchaSolver, CaptchaSolvingService
# get page URL and site_key from your page
page_url = ...
site_key = ...
# init captcha solver
with CaptchaSolver(CaptchaSolvingService.TWOCAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
# solve CAPTCHA
solved = solver.solve_recaptcha_v2(
site_key=site_key,
page_url=page_url,
data_s='<data-s value>', # optional
api_domain='<"google.com" or "recaptcha.net">' # optional
)
# get response token
token = solved.solution.token
Solve reCAPTCHA v2 Invisible
from unicaps import CaptchaSolver, CaptchaSolvingService
# get page url and site_key from your page
page_url = ...
site_key = ...
# init captcha solver
with CaptchaSolver(CaptchaSolvingService.TWOCAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
# solve CAPTCHA
solved = solver.solve_recaptcha_v2(
site_key=site_key,
page_url=page_url,
is_invisible=True,
data_s='<data-s value>', # optional
api_domain='<"google.com" or "recaptcha.net">' # optional
)
# get response token
token = solved.solution.token
Solve reCAPTCHA v2 Enterprise
from unicaps import CaptchaSolver, CaptchaSolvingService
# get page URL, site_key and data_s from your page
page_url = ...
site_key = ...
data_s = ...
# init captcha solver
with CaptchaSolver(CaptchaSolvingService.TWOCAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
# solve CAPTCHA
solved = solver.solve_recaptcha_v2(
site_key=site_key,
page_url=page_url,
is_enterprise=True,
data_s=data_s, # optional
api_domain='<"google.com" or "recaptcha.net">' # optional
)
# get response token
token = solved.solution.token
Solve reCAPTCHA v3
from unicaps import CaptchaSolver, CaptchaSolvingService
# get CAPTCHA params from the target page/site
page_url = ...
site_key = ...
action = ...
min_score = 0.7
# init captcha solver
with CaptchaSolver(CaptchaSolvingService.TWOCAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
# solve CAPTCHA
solved = solver.solve_recaptcha_v3(
site_key=site_key,
page_url=page_url,
action=action, # optional
min_score=min_score, # optional
api_domain='<"google.com" or "recaptcha.net">' # optional
)
# get response token
token = solved.solution.token
Solve reCAPTCHA v3 Enterprise
from unicaps import CaptchaSolver, CaptchaSolvingService
# get CAPTCHA params from the target page/site
page_url = ...
site_key = ...
action = ...
min_score = 0.7
# init captcha solver
with CaptchaSolver(CaptchaSolvingService.TWOCAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
# solve CAPTCHA
solved = solver.solve_recaptcha_v3(
site_key=site_key,
page_url=page_url,
is_enterprise=True,
action=action, # optional
min_score=min_score, # optional
api_domain='<"google.com" or "recaptcha.net">' # optional
)
# get response token
token = solved.solution.token
Solve hCaptcha
from unicaps import CaptchaSolver, CaptchaSolvingService
# get CAPTCHA params from the target page/site
page_url = ...
site_key = ...
# init captcha solver
with CaptchaSolver(CaptchaSolvingService.TWOCAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
# solve CAPTCHA
solved = solver.solve_hcaptcha(
site_key=site_key,
page_url=page_url,
api_domain=<"hcaptcha.com" or "js.hcaptcha.com"> # optional
)
# get response token
token = solved.solution.token
Solve hCaptcha Invisible
from unicaps import CaptchaSolver, CaptchaSolvingService
# get CAPTCHA params from the target page/site
page_url = ...
site_key = ...
# init captcha solver
with CaptchaSolver(CaptchaSolvingService.TWOCAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
# solve CAPTCHA
solved = solver.solve_hcaptcha(
site_key=site_key,
page_url=page_url,
is_invisible=True,
api_domain=<"hcaptcha.com" or "js.hcaptcha.com"> # optional
)
# get response token
token = solved.solution.token
Solve FunCaptcha
from unicaps import CaptchaSolver, CaptchaSolvingService
# get CAPTCHA params from the target page/site
public_key = ...
page_url = ...
# init captcha solver
with CaptchaSolver(CaptchaSolvingService.TWOCAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
# solve CAPTCHA
solved = solver.solve_funcaptcha(
public_key=public_key,
page_url=page_url,
service_url='<value of surl parameter>', # optional
blob='<value of data[blob] parameter>' # optional
)
# get response token
token = solved.solution.token
Solve KeyCaptcha
from unicaps import CaptchaSolver, CaptchaSolvingService
# get CAPTCHA params from the target page/site
page_url = ...
user_id = ...
session_id = ...
ws_sign = ...
ws_sign2 = ...
# init captcha solver
with CaptchaSolver(CaptchaSolvingService.TWOCAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
# solve CAPTCHA
solved = solver.solve_keycaptcha(
page_url=page_url,
user_id=user_id,
session_id=session_id,
ws_sign=ws_sign,
ws_sign2=ws_sign2
)
# get response token
token = solved.solution.token
Solve Geetest
from unicaps import CaptchaSolver, CaptchaSolvingService
# get CAPTCHA params from the target page/site
page_url = ...
gt_key = ...
challenge = ...
# init captcha solver
with CaptchaSolver(CaptchaSolvingService.TWOCAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
# solve CAPTCHA
solved = solver.solve_geetest(
page_url=page_url,
gt_key=gt_key,
challenge=challenge,
api_server='<value of api_server parameter>' # optional
)
# get response token
token = solved.solution.token
Solve Geetest v4
from unicaps import CaptchaSolver, CaptchaSolvingService
# get CAPTCHA params from the target page/site
page_url = ...
captcha_id = ...
# init captcha solver
with CaptchaSolver(CaptchaSolvingService.TWOCAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
# solve CAPTCHA
solved = solver.solve_geetest_v4(
page_url=page_url,
captcha_id=captcha_id
)
# get solution data
lot_number = solved.solution.lot_number
pass_token = solved.solution.pass_token
gen_time = solved.solution.gen_time
captcha_output = solved.solution.captcha_output
Solve Capy Puzzle
from unicaps import CaptchaSolver, CaptchaSolvingService
# get CAPTCHA params from the target page/site
site_key = ...
page_url = ...
# init captcha solver
with CaptchaSolver(CaptchaSolvingService.TWOCAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
# solve CAPTCHA
solved = solver.solve_capy_puzzle(
site_key=site_key,
page_url=page_url,
api_server='<for example "https://api.capy.me">', # optional
challenge_type='<"puzzle" or "avatar">' # optional
)
# get solution data
captchakey = solved.solution.captchakey
challengekey = solved.solution.challengekey
answer = solved.solution.answer
Solve a text CAPTCHA
from unicaps import CaptchaSolver, CaptchaSolvingService
from unicaps.common import CaptchaAlphabet, WorkerLanguage
# init captcha solver
with CaptchaSolver(CaptchaSolvingService.TWOCAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
# solve CAPTCHA
solved = solver.solve_text_captcha(
text='Si mañana es domingo, ¿qué día es hoy?',
alphabet=CaptchaAlphabet.LATIN, # optional
language=WorkerLanguage.SPANISH # optional
)
# get answer
answer = solved.solution.text # Sábado
Error handling
Catch exceptions
from unicaps import CaptchaSolver, CaptchaSolvingService, exceptions
# init captcha solver
with CaptchaSolver(CaptchaSolvingService.TWOCAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
# solve CAPTCHA
try:
solved = solver.solve_recaptcha_v2(
site_key=site_key,
page_url=page_url
)
except exceptions.AccessDeniedError: # wrong API key or the current IP is banned
pass
except exceptions.LowBalanceError: # low balance
pass
except exceptions.ServiceTooBusy: # no available slots to solve CAPTCHA
pass
except exceptions.SolutionWaitTimeout: # haven't received a solution within N minutes
pass
except exceptions.TooManyRequestsError: # request limit exceeded
pass
except exceptions.BadInputDataError: # bad CAPTCHA data (bad image, wrong URL, etc.)
pass
except exceptions.UnableToSolveError: # CAPTCHA unsolvable
pass
except exceptions.ProxyError: # bad proxy
pass
except exceptions.NetworkError: # network connection error
pass
else:
# get response token
token = solved.solution.token
Misc
Create a task and wait for the result
from unicaps import CaptchaSolver, CaptchaSolvingService
from unicaps.captcha import RecaptchaV2
# get page URL and site_key from your page
page_url = ...
site_key = ...
# init captcha solver
with CaptchaSolver(CaptchaSolvingService.TWOCAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
# create a task
task = solver.create_task(
RecaptchaV2(site_key, page_url)
)
# print task ID
print(task.task_id)
# wait for task to be completed
solved = task.wait()
# get response token
token = solved.solution.token
Add proxy, cookies and User-Agent
from unicaps import CaptchaSolver, CaptchaSolvingService
from unicaps.proxy import ProxyServer
# get page URL and site_key from your page
page_url = ...
site_key = ...
proxy = 'http://user:password@domain.com:8080'
user_agent = '<USER AGENT STRING>'
cookies = {'name': 'value', ...}
# init captcha solver
with CaptchaSolver(CaptchaSolvingService.TWOCAPTCHA, "<PLACE YOUR API KEY HERE>") as solver:
# solve CAPTCHA
solved = solver.solve_recaptcha_v2(
site_key=site_key,
page_url=page_url,
proxy=ProxyServer(proxy),
user_agent=user_agent,
cookies=cookies
)
# get response token
token = solved.solution.token
Real-life code examples
Examples