From ba77ae83bb92e6401f3a3e0c893c4dca78d3493f Mon Sep 17 00:00:00 2001 From: Maksim S Date: Mon, 6 May 2024 11:05:36 +0200 Subject: [PATCH] - Added description of parameters to method documentation in solver.py file (#79) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Updated the “see more info in the API docs” link in the README.md file - Added a description of methods supporting proxies for the solution and information about whether we have our own proxy for customers in the proxies section in the README.md file - Added extended examples amazon_waf_options.py, geetest_v4_options,.py, turnstile_options.py to examples. - Added data parameter to hcaptcha_options.py example - Changed the name of the sol=>solver variable in the example file keycaptcha_options.py - Added package description to __init__.py file Signed-off-by: Maxim S --- README.md | 33 +- examples/amazon_waf_options.py | 47 ++ examples/geetest_v4_options.py | 41 ++ examples/hcaptcha_options.py | 15 +- examples/keycaptcha_options.py | 39 +- examples/turnstile_options.py | 46 ++ twocaptcha/__init__.py | 10 + twocaptcha/solver.py | 772 +++++++++++++++++++++------------ 8 files changed, 694 insertions(+), 309 deletions(-) create mode 100644 examples/amazon_waf_options.py create mode 100644 examples/geetest_v4_options.py create mode 100644 examples/turnstile_options.py diff --git a/README.md b/README.md index 7cbc618..b0474ec 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ The easiest way to quickly integrate the 2Captcha captcha-solving service into y - [Friendly Captcha](#friendly-captcha) - [Cutcaptcha](#cutcaptcha) - [Other methods](#other-methods) - - [send / getResult](#send--getresult) + - [send / get_result](#send--getresult) - [balance](#balance) - [report](#report) - [Error handling](#error-handling) @@ -80,7 +80,7 @@ solver = TwoCaptcha(**config) | pollingInterval | 10 | Interval in seconds between requests to `res.php` API endpoint, setting values less than 5 seconds is not recommended | > **IMPORTANT:** once `callback` is defined for `TwoCaptcha` instance, all methods return only the captcha ID and DO NOT poll the API to get the result. The result will be sent to the callback URL. -To get the answer manually use [getResult method](#send--getresult) +To get the answer manually use [get_result method](#send--getresult) ## Solve captcha When you submit any image-based captcha use can provide additional options to help 2captcha workers to solve it properly. @@ -162,20 +162,21 @@ result = solver.geetest(gt='f1ab2cdefa3456789012345b6c78d90e', ``` -### hCaptcha -Use this method to solve the hCaptcha challenge. Returns a token to bypass the captcha. +### GeeTest v4 +Use this method to solve GeeTest v4. Returns the response in JSON. ```python -result = solver.hcaptcha(sitekey='10000000-ffff-ffff-ffff-000000000001', - url='https://www.site.com/page/', +result = solver.geetest_v4(captcha_id='e392e1d7fd421dc63325744d5a2b9c73', + url='https://www.site.com/page/', param1=..., ...) ``` -### GeeTest v4 -Use this method to solve GeeTest v4. Returns the response in JSON. + +### hCaptcha +Use this method to solve the hCaptcha challenge. Returns a token to bypass the captcha. ```python -result = solver.geetest_v4(captcha_id='e392e1d7fd421dc63325744d5a2b9c73', - url='https://www.site.com/page/', +result = solver.hcaptcha(sitekey='10000000-ffff-ffff-ffff-000000000001', + url='https://www.site.com/page/', param1=..., ...) ``` @@ -299,7 +300,7 @@ result = solver.cutcaptcha(misery_key='ad52c87af17e2ec09b8d918c9f00416b1cb8c320' ## Other methods -### send / getResult +### send / get_result These methods can be used for manual captcha submission and answer polling. ```python import time @@ -347,7 +348,11 @@ except TimeoutException as 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. +You can pass your proxy as an additional argument for methods: recaptcha, funcaptcha, geetest, geetest v4, hcaptcha, +keycaptcha, capy pazzle, grid, rotate, lemin, atbcaptcha, turnstile, amazon waf, mtcaptcha, friendly captcha, cutcaptcha. +The proxy will be forwarded to the API to solve the captcha. + +We have our own proxies that we can offer you. [Buy residential proxies] for avoid restrictions and blocks. [Quick start]. ```python proxy={ @@ -377,7 +382,9 @@ async def captchaSolver(image): [2Captcha]: https://2captcha.com/ [2captcha sofware catalog]: https://2captcha.com/software [pingback settings]: https://2captcha.com/setting/pingback -[post options]: https://2captcha.com/2captcha-api#normal_post +[post options]: https://2captcha.com/2captcha-api#solving_normal_captcha [list of supported languages]: https://2captcha.com/2captcha-api#language [examples directory]: /examples [asyncio]: https://docs.python.org/3/library/asyncio.html +[Buy residential proxies]: https://2captcha.com/proxy/residential-proxies +[Quick start]: https://2captcha.com/proxy?openAddTrafficModal=true diff --git a/examples/amazon_waf_options.py b/examples/amazon_waf_options.py new file mode 100644 index 0000000..c1bbbb6 --- /dev/null +++ b/examples/amazon_waf_options.py @@ -0,0 +1,47 @@ +import sys +import os + +sys.path.append(os.path.dirname(os.path.dirname(os.path.realpath(__file__)))) + +from twocaptcha import TwoCaptcha + +# in this example we store the API key inside environment variables that can be set like: +# export APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Linux or macOS +# set APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Windows +# you can just set the API key directly to it's value like: +# api_key="1abc234de56fab7c89012d34e56fa7b8" + +api_key = os.getenv('APIKEY_2CAPTCHA', 'YOUR_API_KEY') + + +config = { + 'server': '2captcha.com', # can be also set to 'rucaptcha.com' + 'apiKey': api_key, + 'softId': 123, + # 'callback': 'https://your.site/result-receiver', # if set, sovler with just return captchaId, not polling API for the answer + 'defaultTimeout': 120, + 'recaptchaTimeout': 600, + 'pollingInterval': 10, + } + +solver = TwoCaptcha(**config) + +try: + result = solver.amazon_waf(sitekey='AQIDAHjcYu/GjX+QlghicBgQ/7bFaQZ+m5FKCMDnO+vTbNg96AGIqvS8v6ScFa8ZpNRrlQgKAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMx9gxoe10Zg35PWhzAgEQgDvUtMMkqkFQByMLK2329D8iX4mjvaTuUhU70LD4vLp54v3+4K1nYY2hB+OM1hMbncnMbP63y4UOrY77jg==', + iv='CgAGVTNd9JAAAAnB', + context='Lte3LdSjiAN6nNcV0omaNt/ydFmd/eTwRCxYEeuW97LZe3IbAXWi4Er9CWQ3HbDgJ0KSpDgwyoskjKCK4VRQzYufPCdrfCYCveZCt9pMNoAluEtj0oix2GXOPVkw2d4bYOg3MtY5ZUHLR3L467NEInnRE99w5NOgokH5Ie7eOi5sYAqYtZrHABGEgrdAOVvU7bcwvrCERi9wB/WS75geb3oFy6z7Apue9GFa86Ld20jjgy4LWfaen+2fpfKHmCHTKVWfto17Bg+l5i0sr+uFRzpk1We64Fhh1Wl1NHF6M6dpS5s=', + url='https://efw47fpad9.execute-api.us-east-1.amazonaws.com/latest', + challenge_script="https://41bcdd4fb3cb.610cd090.us-east-1.token.awswaf.com/41bcdd4fb3cb/0d21de737ccb/cd77baa6c832/challenge.js", + captcha_script="https://41bcdd4fb3cb.610cd090.us-east-1.captcha.awswaf.com/41bcdd4fb3cb/0d21de737ccb/cd77baa6c832/captcha.js", + callback="https://mysite.com/2captcha.txt" + # proxy={ + # 'type': 'HTTPS', + # 'uri': 'login:password@IP_address:PORT' + # } + ) + +except Exception as e: + sys.exit(e) + +else: + sys.exit('result: ' + str(result)) diff --git a/examples/geetest_v4_options.py b/examples/geetest_v4_options.py new file mode 100644 index 0000000..1a32ef0 --- /dev/null +++ b/examples/geetest_v4_options.py @@ -0,0 +1,41 @@ +import sys +import os +import requests +sys.path.append(os.path.dirname(os.path.dirname(os.path.realpath(__file__)))) + +from twocaptcha import TwoCaptcha + +# in this example we store the API key inside environment variables that can be set like: +# export APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Linux or macOS +# set APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Windows +# you can just set the API key directly to it's value like: +# api_key="1abc234de56fab7c89012d34e56fa7b8" + +api_key = os.getenv('APIKEY_2CAPTCHA', 'YOUR_API_KEY') + +config = { + 'server': '2captcha.com', # can be also set to 'rucaptcha.com' + 'apiKey': api_key, + 'softId': 123, + # 'callback': 'https://your.site/result-receiver', # if set, sovler with just return captchaId, not polling API for the answer + 'defaultTimeout': 120, + 'recaptchaTimeout': 600, + 'pollingInterval': 10, + } + +solver = TwoCaptcha(**config) + +try: + result = solver.geetest_v4(captcha_id='e392e1d7fd421dc63325744d5a2b9c73', + url='https://2captcha.com/demo/geetest-v4', + # proxy={ + # 'type': 'HTTPS', + # 'uri': 'login:password@IP_address:PORT' + # } + ) + +except Exception as e: + sys.exit(e) + +else: + sys.exit('result: ' + str(result)) diff --git a/examples/hcaptcha_options.py b/examples/hcaptcha_options.py index f88a7c3..7a56dc9 100644 --- a/examples/hcaptcha_options.py +++ b/examples/hcaptcha_options.py @@ -27,12 +27,15 @@ solver = TwoCaptcha(**config) try: - result = solver.hcaptcha(sitekey='3ceb8624-1970-4e6b-91d5-70317b70b651', - url='https://2captcha.com/demo/hcaptcha?difficulty=easy', - # proxy={ - # 'type': 'HTTPS', - # 'uri': 'login:password@IP_address:PORT' - # } + result = solver.hcaptcha(sitekey='f7de0da3-3303-44e8-ab48-fa32ff8ccc7b', + url='https://2captcha.com/ru/demo/hcaptcha-invisible', + # invisible=1, + # data="rqdata", + # useragent="", + # proxy={ + # 'type': 'HTTPS', + # 'uri': 'login:password@IP_address:PORT' + # } ) except Exception as e: diff --git a/examples/keycaptcha_options.py b/examples/keycaptcha_options.py index 39553b3..b1518dc 100644 --- a/examples/keycaptcha_options.py +++ b/examples/keycaptcha_options.py @@ -1,22 +1,41 @@ import sys -'../../' in sys.path or sys.path.append('../../') +import os + +sys.path.append(os.path.dirname(os.path.dirname(os.path.realpath(__file__)))) from twocaptcha import TwoCaptcha +# in this example we store the API key inside environment variables that can be set like: +# export APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Linux or macOS +# set APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Windows +# you can just set the API key directly to it's value like: +# api_key="1abc234de56fab7c89012d34e56fa7b8" + +api_key = os.getenv('APIKEY_2CAPTCHA', 'YOUR_API_KEY') -sol = TwoCaptcha('YOUR_API_KEY', defaultTimeout=120) +config = { + 'server': '2captcha.com', # can be also set to 'rucaptcha.com' + 'apiKey': api_key, + 'softId': 123, + # 'callback': 'https://your.site/result-receiver', # if set, sovler with just return captchaId, not polling API for the answer + 'defaultTimeout': 120, + 'recaptchaTimeout': 600, + 'pollingInterval': 10, + } +solver = TwoCaptcha(**config) try: - result = sol.keycaptcha(s_s_c_user_id = 10, - s_s_c_session_id = '493e52c37c10c2bcdf4a00cbc9ccd1e8', - s_s_c_web_server_sign = '9006dc725760858e4c0715b835472f22-pz-', - s_s_c_web_server_sign2 = '2ca3abe86d90c6142d5571db98af6714', - url = 'https://www.keycaptcha.ru/demo-magnetic/', - proxy = { - 'type': 'HTTPS', - 'uri': 'login:password@IP_address:PORT'}) + result = solver.keycaptcha(s_s_c_user_id = 184015, + s_s_c_session_id = 'c32c9934c68b2968bee0332b9346da42', + s_s_c_web_server_sign = 'c93c8d136d5ee6ee6fe27ab2be54901d', + s_s_c_web_server_sign2 = 'eec85fcfeda28bffd7764d712d4089e7', + url = 'https://2captcha.com/ru/demo/keycaptcha' + # proxy = { + # 'type': 'HTTPS', + # 'uri': 'login:password@IP_address:PORT'} + ) except Exception as e: diff --git a/examples/turnstile_options.py b/examples/turnstile_options.py new file mode 100644 index 0000000..ed3f236 --- /dev/null +++ b/examples/turnstile_options.py @@ -0,0 +1,46 @@ +import sys +import os + +sys.path.append(os.path.dirname(os.path.dirname(os.path.realpath(__file__)))) + +from twocaptcha import TwoCaptcha + +# in this example we store the API key inside environment variables that can be set like: +# export APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Linux or macOS +# set APIKEY_2CAPTCHA=1abc234de56fab7c89012d34e56fa7b8 on Windows +# you can just set the API key directly to it's value like: +# api_key="1abc234de56fab7c89012d34e56fa7b8" + +api_key = os.getenv('APIKEY_2CAPTCHA', 'YOUR_API_KEY') + + +config = { + 'server': '2captcha.com', # can be also set to 'rucaptcha.com' + 'apiKey': api_key, + 'softId': 123, + # 'callback': 'https://your.site/result-receiver', # if set, sovler with just return captchaId, not polling API for the answer + 'defaultTimeout': 120, + 'recaptchaTimeout': 600, + 'pollingInterval': 10, + } + +solver = TwoCaptcha(**config) + +try: + result = solver.turnstile(sitekey='0x4AAAAAAAVrOwQWPlm3Bnr5', + url='https://2captcha.com/demo/turnstile', + # data="str", + # pagedata="str", + # action="str", + # useragent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36" + # proxy={ + # 'type': 'HTTPS', + # 'uri': 'login:password@IP_address:PORT' + # } + ) + +except Exception as e: + sys.exit(e) + +else: + sys.exit('result: ' + str(result)) diff --git a/twocaptcha/__init__.py b/twocaptcha/__init__.py index f88ffc7..a27bf88 100644 --- a/twocaptcha/__init__.py +++ b/twocaptcha/__init__.py @@ -2,4 +2,14 @@ from .solver import (TwoCaptcha, SolverExceptions, ValidationException, NetworkException, ApiException, TimeoutException) +""" +Python 3 package for easy integration with the API of 2captcha captcha solving service to bypass recaptcha, hcaptcha, +funcaptcha, geetest and solve any other captchas. + +website 2captcha [https://2captcha.com/] +support@2captcha.com +# License: MIT +""" + +__author__ = '2captcha' __version__ = '1.2.4' diff --git a/twocaptcha/solver.py b/twocaptcha/solver.py index 2d829a8..a8ef893 100755 --- a/twocaptcha/solver.py +++ b/twocaptcha/solver.py @@ -54,27 +54,47 @@ def __init__(self, self.exceptions = SolverExceptions def normal(self, file, **kwargs): - ''' - Wrapper for solving normal captcha (image) - - Required: - file (image, base64, or url) - - Optional params: - - phrase - numeric - minLen - maxLen - phrase - caseSensitive - calc - lang - hintText - hintImg - softId - callback - proxy = {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}) + '''Wrapper for solving normal captcha (image). + + Parameters + __________ + file : file + Captcha image file. * required if you submit image as a file (method=post). + body : str + Base64-encoded captcha image. * required if you submit image as Base64-encoded string (method=base64). + phrase : int, optional + 0 - captcha contains one word. 1 - captcha contains two or more words. + Default: 0. + numeric : int, optional + 0 - not specified. 1 - captcha contains only numbers. 2 - captcha contains only letters. 3 - captcha + contains only numbers OR only letters. 4 - captcha MUST contain both numbers AND letters. + Default: 0 + minLen : int, optional + 0 - not specified. 1..20 - minimal number of symbols in captcha. + Default: 0. + maxLen : int, optional + 0 - not specified. 1..20 - maximal number of symbols in captcha. + Default: 0. + caseSensitive : int, optional + 0 - captcha in not case sensitive. 1 - captcha is case sensitive. + Default: 0. + calc : int, optional + 0 - not specified. 1 - captcha requires calculation (e.g. type the result 4 + 8 = ). + Default: 0. + lang : str, optional + Language code. See the list of supported languages https://2captcha.com/2captcha-api#language. + hintText : str, optional + Max 140 characters. Endcoding: UTF-8. Text will be shown to worker to help him to solve the captcha correctly. + For example: type red symbols only. + hintImg : img, optional + Max 400x150px, 100 kB. Image with instruction for solving reCAPTCHA. Not required if you're sending + instruction as text with textinstructions. + softId : int, optional + ID of software developer. Developers who integrated their software with 2Captcha get reward: 10% of + spendings of their software users. + callback : str, optional + URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on + the server. More info here https://2captcha.com/2captcha-api#pingback. ''' method = self.get_method(file) @@ -82,15 +102,16 @@ def normal(self, file, **kwargs): return result def audio(self, file, lang, **kwargs): - ''' - Wrapper for solving audio captcha - - Required: - file (base64, or url to mp3 file) - lang ("en", "ru", "de", "el", "pt") + '''Wrapper for solving audio captcha. - Optional params: + Parameters + __________ + body : str + Base64 encoded audio file in mp3 format. Max file size: 1 MB. + lang : str + The language of audio record. Supported languages are: "en", "ru", "de", "el", "pt", "fr". ''' + method = "audio" if not file: @@ -108,47 +129,70 @@ def audio(self, file, lang, **kwargs): else: raise ValidationException('File extension is not .mp3 or it is not a base64 string.') - if not lang or lang not in ("en", "ru", "de", "el", "pt"): - raise ValidationException(f'Lang not in "en", "ru", "de", "el", "pt". You send {lang}') + if not lang or lang not in ("en", "ru", "de", "el", "pt", "fr"): + raise ValidationException(f'Lang not in "en", "ru", "de", "el", "pt", "fr". You send {lang}') result = self.solve(body=body, method=method, **kwargs) return result def text(self, text, **kwargs): - ''' - Wrapper for solving text captcha + '''Wrapper for solving text captcha. - Required: - text - - Optional params: - - lang - softId - callback + Parameters + __________ + text : str + Max 140 characters. Endcoding: UTF-8. Text will be shown to worker to help him to solve the captcha correctly. + For example: type red symbols only. + lang: str, optional + Language code. See the list of supported languages https://2captcha.com/2captcha-api#language. + softId : int, optional + ID of software developer. Developers who integrated their software with 2Captcha get reward: 10% of + spendings of their software users. + callback : str, optional + URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on + the server. More info here https://2captcha.com/2captcha-api#pingback. ''' result = self.solve(text=text, method='post', **kwargs) return result def recaptcha(self, sitekey, url, version='v2', enterprise=0, **kwargs): - ''' - Wrapper for solving recaptcha (v2, v3) + '''Wrapper for solving recaptcha (v2, v3). - Required: - sitekey - url - - Optional params: - - invisible - version - enterprise - action - score - softId - callback - proxy = {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}) + Parameters + _______________ + sitekey : str + Value of sitekey parameter you found on page. + url : str + Full URL of the page where you see the reCAPTCHA. + domain : str, optional + Domain used to load the captcha: google.com or recaptcha.net. Default: google.com. + invisible : int, optional + 1 - means that reCAPTCHA is invisible. 0 - normal reCAPTCHA. Default: 0. + version : str, optional + v3 — defines that you're sending a reCAPTCHA V3. Default: v2. + enterprise : str, optional + 1 - defines that you're sending reCAPTCHA Enterpise. Default: 0. + action : str, optional + Value of action parameter you found on page. Default: verify. + score : str, only for v3, optional + The score needed for resolution. Currently, it's almost impossible to get token with score higher than 0.3. + Default: 0.4. + data-s : str, only for v2, optional + Value of data-s parameter you found on page. Curenttly applicable for Google Search and other Google services. + cookies : str, only for v2, optional + Your cookies that will be passed to our worker who solve the captha. We also return worker's cookies in the + response if you use json=1. Format: KEY:Value, separator: semicolon, example: KEY1:Value1;KEY2:Value2; + userAgent : str, only for v2, optional + Your userAgent that will be passed to our worker and used to solve the captcha. + softId : int, optional + ID of software developer. Developers who integrated their software with 2Captcha get reward: 10% of + spendings of their software users. + callback : str, optional + URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on + the server. More info here https://2captcha.com/2captcha-api#pingback. + proxy : dict, optional + {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}. ''' params = { @@ -164,21 +208,28 @@ def recaptcha(self, sitekey, url, version='v2', enterprise=0, **kwargs): return result def funcaptcha(self, sitekey, url, **kwargs): - ''' - Wrapper for solving funcaptcha + '''Wrapper for solving funcaptcha. - Required: - sitekey - url - - Optional params: - - surl - userAgent - softId - callback - proxy = {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}) - **{'data[key]': 'anyStringValue'} + Parameters + __________ + sitekey : str + Value of pk or data-pkey parameter you found on page. + url : str + Full URL of the page where you see the FunCaptcha. + surl : str, optional + Value of surl parameter you found on page. + userAgent: str, optional + Tells us to use your user-agent value. + data[key] : str, optional + Custom data to pass to FunCaptcha. For example: data[blob]=stringValue. + softId : str, optional + ID of software developer. Developers who integrated their software with 2Captcha get reward: 10% of + spendings of their software users. + callback : str, optional + URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on + the server. More info here https://2captcha.com/2captcha-api#pingback. + proxy : dict, optional + {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}. ''' result = self.solve(publickey=sitekey, @@ -188,20 +239,34 @@ def funcaptcha(self, sitekey, url, **kwargs): return result def geetest(self, gt, challenge, url, **kwargs): - ''' - Wrapper for solving geetest captcha - - Required: - gt - challenge - url - - Optional params: - - apiServer - softId - callback - proxy = {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}) + '''Wrapper for solving geetest captcha. + + Parameters: + __________ + gt : str + Value of gt parameter you found on target website. + challenge : str + Value of challenge parameter you found on target website. + url : str + Full URL of the page where you see Geetest captcha. + offline : num, optional + In rare cases initGeetest can be called with offline parameter. If the call uses offline: true, set the + value to 1. Default: 0. + new_captcha : num, optional + In rare cases initGeetest can be called with new_captcha parameter. If the call uses new_captcha: true, set + the value to 1. Mostly used with offline parameter. + userAgent : str, optional + Your userAgent that will be passed to our worker and used to solve the captcha. + apiServer : str, optional + Value of api_server parameter you found on target website. + softId : int, optional + ID of software developer. Developers who integrated their software with 2Captcha get reward: 10% of + spendings of their software users. + callback : str, optional + URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on + the server. More info here https://2captcha.com/2captcha-api#pingback. + proxy : dict, optional + {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}. ''' result = self.solve(gt=gt, @@ -212,20 +277,30 @@ def geetest(self, gt, challenge, url, **kwargs): return result def hcaptcha(self, sitekey, url, **kwargs): - ''' - Wrapper for solving hcaptcha - - Required: - sitekey - url - - Optional params: + '''Wrapper for solving hcaptcha. - invisible - data - softId - callback - proxy = {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}) + Parameters + __________ + sitekey : str + Value of data-sitekey parameter you found on page. + url : str + Full URL of the page where you bypass the captcha. + invisible : num, optional + Use 1 for invisible version of hcaptcha. Currently it is a very rare case. + Default: 0. + data : str, optional + Custom data that is used in some implementations of hCaptcha, mostly with invisible=1. In most cases you see + it as rqdata inside network requests. Format: "data": "rqDataValue". + domain : str, optional + Domain used to load the captcha: hcaptcha.com or js.hcaptcha.com. Default: hcaptcha.com. + softId : int, optional + ID of software developer. Developers who integrated their software with 2Captcha get reward: 10% of + spendings of their software users. + callback : str, optional + URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on + the server. More info here https://2captcha.com/2captcha-api#pingback. + proxy : dict, optional + {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}. ''' result = self.solve(sitekey=sitekey, @@ -237,21 +312,28 @@ def hcaptcha(self, sitekey, url, **kwargs): def keycaptcha(self, s_s_c_user_id, s_s_c_session_id, s_s_c_web_server_sign, s_s_c_web_server_sign2, url, **kwargs): - ''' - Wrapper for solving + '''Wrapper for solving. - Required: - s_s_c_user_id - s_s_c_session_id - s_s_c_web_server_sign - s_s_c_web_server_sign2 - url - - Optional params: - - softId - callback - proxy = {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}) + Parameters + __________ + s_s_c_user_id : str + Value of s_s_c_user_id parameter you found on page. + s_s_c_session_id : str + Value of s_s_c_session_id parameter you found on page. + s_s_c_web_server_sign : str + Value of s_s_c_web_server_sign parameter you found on page. + s_s_c_web_server_sign2 : str + Value of s_s_c_web_server_sign2 parameter you found on page. + url : str + Full URL of the page where you see the KeyCaptcha. + softId : int, optional + ID of software developer. Developers who integrated their software with 2Captcha get reward: 10% of + spendings of their software users. + callback : str, optional + URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on + the server. More info here https://2captcha.com/2captcha-api#pingback. + proxy : dict, optional + {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}. ''' params = { @@ -268,18 +350,26 @@ def keycaptcha(self, s_s_c_user_id, s_s_c_session_id, return result def capy(self, sitekey, url, **kwargs): - ''' - Wrapper for solving capy + '''Wrapper for solving capy. - Required: - sitekey - url - - Optional params: - - softId - callback - proxy = {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}) + Parameters + __________ + sitekey : str + The domain part of script URL you found on page. Default value: https://jp.api.capy.me/. + url : str + Full URL of the page where you see the captcha. + api_server : str, optional + The domain part of script URL you found on page. Default value: https://jp.api.capy.me/. + version : str, optional + The version of captcha task: puzzle (assemble a puzzle) or avatar (drag an object). Default: puzzle. + softId : int, optional + ID of software developer. Developers who integrated their software with 2Captcha get reward: 10% of + spendings of their software users. + callback : str, optional + URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on + the server. More info here https://2captcha.com/2captcha-api#pingback. + proxy : dict, optional + {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}. ''' result = self.solve(captchakey=sitekey, @@ -289,24 +379,40 @@ def capy(self, sitekey, url, **kwargs): return result def grid(self, file, **kwargs): - ''' - Wrapper for solving grid captcha (image) - + '''Wrapper for solving grid captcha (image). + Required: - file (image or base64) - - Optional params: - - rows - cols - previousId - canSkip - lang - hintImg - hintText - softId - callback - proxy = {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}) + file : file + Captcha image file. * required if you submit image as a file (method=post). + body : str + Base64-encoded captcha image. * required if you submit image as Base64-encoded string (method=base64). + hintText : str + Max 140 characters. Endcoding: UTF-8. Text with instruction for solving reCAPTCHA. For example: select images + with trees. Not required if you're sending instruction as an image with imginstructions. + hintImg : img + Max 400x150px, 100 kB. Image with instruction for solving reCAPTCHA. Not required if you're sending + instruction as text with textinstructions. + rows : int, optional + Number of rows in reCAPTCHA grid. + cols : itn, optional + Number of columns in reCAPTCHA grid. + previousId : str, optional + Id of your previous request with the same captcha challenge. + canSkip : int, optional + 0 - not specified. 1 - possibly there's no images that fit the instruction. Set the value to 1 only if it's + possible that there's no images matching to the instruction. We'll provide a button "No matching images" to + worker, and you will receive No_matching_images as answer. + Default: 0. + lang: str, optional + Language code. See the list of supported languages https://2captcha.com/2captcha-api#language. + softId : int, optional + ID of software developer. Developers who integrated their software with 2Captcha get reward: 10% of + spendings of their software users. + callback : str, optional + URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on + the server. More info here https://2captcha.com/2captcha-api#pingback. + proxy : dict, optional + {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}. ''' method = self.get_method(file) @@ -321,22 +427,34 @@ def grid(self, file, **kwargs): return result def canvas(self, file, **kwargs): - ''' - Wrapper for solving canvas captcha (image) - - Required: - file (image or base64) - - Optional params: - - previousId - canSkip - lang - hintImg - hintText - softId - callback - proxy = {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}) + '''Wrapper for solving canvas captcha (image). + + Parameters + __________ + file : file + Captcha image file. * required if you submit image as a file (method=post). + body : str + Base64-encoded captcha image. * required if you submit image as Base64-encoded string (method=base64). + hintText : str + Max 140 characters. Endcoding: UTF-8. Text with instruction for solving reCAPTCHA. For example: select + images with trees. Not required if you're sending instruction as an image with imginstructions. + hintImg : img + Max 400x150px, 100 kB. Image with instruction for solving reCAPTCHA. Not required if you're sending + instruction as text with textinstructions. + canSkip : int, optional + 0 - not specified. 1 - possibly there's no images that fit the instruction. Set the value to 1 only if it's + possible that there's no images matching to the instruction. We'll provide a button "No matching images" to + worker, and you will receive No_matching_images as answer. + Default: 0. + lang : int, optional + 0 - not specified. 1 - Cyrillic captcha. 2 - Latin captcha. + Default: 0. + softId : int, optional + ID of software developer. Developers who integrated their software with 2Captcha get reward: 10% of + spendings of their software users. + callback : str, optional + URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on + the server. More info here https://2captcha.com/2captcha-api#pingback. ''' if not ('hintText' in kwargs or 'hintImg' in kwargs): @@ -356,20 +474,28 @@ def canvas(self, file, **kwargs): return result def coordinates(self, file, **kwargs): - ''' - Wrapper for solving coordinates captcha (image) - - Required: - file (image or base64) - - Optional params: - - hintImg - hintText - lang - softId - callback - proxy = {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}) + '''Wrapper for solving coordinates captcha (image). + + Parameters + __________ + file : file + Captcha image file. * required if you submit image as a file (method=post). + body : str + Base64-encoded captcha image. * required if you submit image as Base64-encoded string (method=base64). + hintText : str + Max 140 characters. Endcoding: UTF-8. Text with instruction for solving the captcha. For example: click on + images with ghosts. Not required if the image already contains the instruction. + hintImg : img + Max 400x150px, 100 kB. Image with instruction for solving reCAPTCHA. Not required if you're sending + instruction as text with textinstructions. + lang : str, optional + Language code. See the list of supported languages https://2captcha.com/2captcha-api#language. + softId : int, optional + ID of software developer. Developers who integrated their software with 2Captcha get reward: 10% of + spendings of their software users. + callback : str, optional + URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on + the server. More info here https://2captcha.com/2captcha-api#pingback. ''' method = self.get_method(file) @@ -384,21 +510,31 @@ def coordinates(self, file, **kwargs): return result def rotate(self, files, **kwargs): - ''' - Wrapper for solving rotate captcha (image) - - Required: - files (images) - - Optional params: - - angle - lang - hintImg - hintText - softId - callback - proxy = {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}) + '''Wrapper for solving rotate captcha (image). + + Parameters + __________ + files : file + Captcha image file. * required if you submit image as a file (method=post). + body : str + Base64-encoded captcha image. * required if you submit image as Base64-encoded string (method=base64). + angle : int, optional + Angle for one rotation step in degrees. If not defined we'll use the default value for FunCaptcha: 40 degrees. + Default: 40. + lang : str, optional + Language code. See the list of supported languages https://2captcha.com/2captcha-api#language. + hintImg : str, optional + Image with instruction for worker to help him to solve captcha correctly. + hintText : str, optional + Text will be shown to worker to help him to to solve captcha correctly. + softId : int, optional + ID of software developer. Developers who integrated their software with 2Captcha get reward: 10% of + spendings of their software users. + callback : str, optional + URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on + the server. More info here https://2captcha.com/2captcha-api#pingback. + proxy : dict, optional + {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}. ''' if isinstance(files, str): @@ -418,16 +554,22 @@ def rotate(self, files, **kwargs): def geetest_v4(self, captcha_id, url, **kwargs): - ''' - Wrapper for solving geetest_v4 captcha - - Required: - captcha_id - url - - Optional params: - + '''Wrapper for solving geetest_v4 captcha. + Parameters + __________ + captcha_id : str + Value of captcha_id parameter you found on target website. + url: str + Full URL of the page where you see Geetest captcha. + softId : int, optional + ID of software developer. Developers who integrated their software with 2Captcha get reward: 10% of + spendings of their software users. + callback : str, optional + URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on + the server. More info here https://2captcha.com/2captcha-api#pingback. + proxy : dict, optional + {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}. ''' result = self.solve(captcha_id=captcha_id, @@ -438,17 +580,26 @@ def geetest_v4(self, captcha_id, url, **kwargs): def lemin(self, captcha_id, div_id, url, **kwargs): - ''' - Wrapper for solving Lemin Cropped Captcha - - Required: - captcha_id - div_id - url - - Optional params: - + '''Wrapper for solving Lemin Cropped Captcha. + Parameters + __________ + captcha_id : str + Value of captcha_id parameter you found on page. + div_id : str + The id of captcha parent div element. + url : str + Full URL of the page where you see the captcha. + api_server : str, optional + The domain part of script URL you found on page. Default value: https://api.leminnow.com/. + softId : int, optional + ID of software developer. Developers who integrated their software with 2Captcha get reward: 10% of + spendings of their software users. + callback : str, optional + URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on + the server. More info here https://2captcha.com/2captcha-api#pingback. + proxy : dict, optional + {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}. ''' result = self.solve(captcha_id=captcha_id, @@ -459,18 +610,22 @@ def lemin(self, captcha_id, div_id, url, **kwargs): return result def atb_captcha(self, app_id, api_server, url, **kwargs): - ''' - Wrapper for solving atbCAPTCHA - - Required: - app_id - api_server - url - - Optional params: + '''Wrapper for solving atbCAPTCHA. + Parameters + __________ + app_id : str + The value of appId parameter in the website source code. + api_server : str + The value of apiServer parameter in the website source code. + url : str + The full URL of target web page where the captcha is loaded. We do not open the page, not a problem if it is + available only for authenticated users. + proxy : dict, optional + {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}. ''' + result = self.solve(app_id=app_id, api_server=api_server, url=url, @@ -480,17 +635,27 @@ def atb_captcha(self, app_id, api_server, url, **kwargs): def turnstile(self, sitekey, url, **kwargs): - ''' - Wrapper for solving Cloudflare Turnstile - - Required: - sitekey - url - - Optional params: - action - data + '''Wrapper for solving Cloudflare Turnstile. + Parameters + __________ + sitekey : str + Value of sitekey parameter you found on page. + url : str + Full URL of the page where you see the captcha. + action : str. optional + Value of optional action parameter you found on page, can be defined in data-action attribute or passed + to turnstile.render call. + data : str, optional + The value of cData passed to turnstile.render call. Also can be defined in data-cdata attribute. + softId : int, optional + ID of software developer. Developers who integrated their software with 2Captcha get reward: 10% of + spendings of their software users. + callback : str, optional + URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on + the server. More info here https://2captcha.com/2captcha-api#pingback. + proxy : dict, optional + {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}. ''' result = self.solve(sitekey=sitekey, @@ -501,17 +666,30 @@ def turnstile(self, sitekey, url, **kwargs): def amazon_waf(self, sitekey, iv, context, url, **kwargs): - ''' - Wrapper for solving Amazon WAF - - Required: - sitekey - iv - context - url - - Optional params: + '''Wrapper for solving Amazon WAF. + Parameters + __________ + sitekey : str + Value of key parameter you found on the page. + iv : str + Value of iv parameter you found on the page. + context : str + Value of optional context parameter you found on page. + url : str + Full URL of the page where you see the captcha. + challenge_script : str, optional + The source URL of challenge.js script on the page. + captcha_script : str, optional + The source URL of captcha.js script on the page. + softId : int, optional + ID of software developer. Developers who integrated their software with 2Captcha get reward: 10% of + spendings of their software users. + callback : str, optional + URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on + the server. More info here https://2captcha.com/2captcha-api#pingback. + proxy : dict, optional + {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}. ''' result = self.solve(sitekey=sitekey, @@ -524,17 +702,22 @@ def amazon_waf(self, sitekey, iv, context, url, **kwargs): return result def mtcaptcha(self, sitekey, url, **kwargs): - ''' - Wrapper for solving MTCaptcha + '''Wrapper for solving MTCaptcha. - Required: - sitekey - url - - Optional params: - softId - callback - proxy = {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}) + Parameters + __________ + sitekey : str + The value of sitekey parameter found on the page. + url : str + Full URL of the page where you solve the captcha. + softId : int, optional + ID of software developer. Developers who integrated their software with 2Captcha get reward: 10% of + spendings of their software users. + callback : str, optional + URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on + the server. More info here https://2captcha.com/2captcha-api#pingback. + proxy : dict, optional + {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}. ''' result = self.solve(sitekey=sitekey, @@ -544,17 +727,22 @@ def mtcaptcha(self, sitekey, url, **kwargs): return result def friendly_captcha(self, sitekey, url, **kwargs): - ''' - Wrapper for solving Friendly Captcha - - Required: - sitekey - url + '''Wrapper for solving Friendly Captcha. - Optional params: - softId - callback - proxy = {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}) + Parameters + __________ + sitekey : str + The value of data-sitekey attribute of captcha's div element on page. + url : str + Full URL of the page where you solve the captcha. + softId : int, optional + ID of software developer. Developers who integrated their software with 2Captcha get reward: 10% of + spendings of their software users. + callback : str, optional + URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on + the server. More info here https://2captcha.com/2captcha-api#pingback. + proxy : dict, optional + {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}. ''' result = self.solve(sitekey=sitekey, @@ -564,18 +752,24 @@ def friendly_captcha(self, sitekey, url, **kwargs): return result def cutcaptcha(self, misery_key, apikey, url, **kwargs): - ''' - Wrapper for solving Friendly Captcha + '''Wrapper for solving Friendly Captcha. - Required: - misery_key - apikey - url - - Optional params: - softId - callback - proxy = {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}) + Parameters + __________ + misery_key : str + The value of CUTCAPTCHA_MISERY_KEY variable defined on page. + apikey : str + The value of data-apikey attribute of iframe's body. Also, the name of javascript file included on the page. + url : str + Full URL of the page where you solve the captcha. + softId : int, optional + ID of software developer. Developers who integrated their software with 2Captcha get reward: 10% of + spendings of their software users. + callback : str, optional + URL for pingback (callback) response that will be sent when captcha is solved. URL should be registered on + the server. More info here https://2captcha.com/2captcha-api#pingback. + proxy : dict, optional + {'type': 'HTTPS', 'uri': 'login:password@IP_address:PORT'}. ''' result = self.solve(misery_key=misery_key, @@ -586,19 +780,19 @@ def cutcaptcha(self, misery_key, apikey, url, **kwargs): return result def solve(self, timeout=0, polling_interval=0, **kwargs): - ''' - sends captcha, receives result - + '''Sends captcha, receives result. Parameters - ---------- + __________ timeout : float + polling_interval : int - **kwargs : all captcha params + **kwargs : dict + all captcha params Returns - ------- + result : string ''' @@ -650,6 +844,15 @@ def get_method(self, file): return {'method': 'post', 'file': file} def send(self, **kwargs): + """This method can be used for manual captcha submission + + Parameters + _________ + kwargs: dict + + Returns + + """ params = self.default_params(kwargs) params = self.rename_params(params) @@ -664,6 +867,16 @@ def send(self, **kwargs): return response[3:] def get_result(self, id_): + """This method can be used for manual captcha answer polling. + + Parameters + __________ + id_ : str + ID of the captcha sent for solution + Returns + + answer : text + """ response = self.api_client.res(key=self.API_KEY, action='get', id=id_) @@ -676,30 +889,29 @@ def get_result(self, id_): return response[3:] def balance(self): - ''' - get my balance + '''Get my balance Returns - ------- - balance : float + balance : float ''' response = self.api_client.res(key=self.API_KEY, action='getbalance') return float(response) def report(self, id_, correct): - ''' - report of solved captcha: good/bad + '''Report of solved captcha: good/bad. Parameters - ---------- - id_ : captcha ID - correct : True/False + __________ + id_ : str + captcha ID + + correct : bool + True/False Returns - ------- - None. + None. '''