2Captcha.com API description is moved here

 

The guide below is no longer updated so please use the new API desciption.

UPD November 24, 2016 We've added new error codes to our API that are corresponding to requests amount limitation. For more info click here.

Visit our examples page and GitHub repo to find examples of code

iMacros form: http://imacros2.2captcha.com

New way to solve recaptchaV2 without browser emulation here


ReCaptcha 2.0 (ASIRA), and FunCaptcha, and ClickCaptcha solving here



Send your CAPTCHAs to 2Captcha.com and get them solved automatically by humans. You can start with getting an API key in your account and apply the following algorithm:

1. Send your image to the 2Captcha.com server.
2. Get the ID of the picture
3. Start the cycle that checks if the CAPTCHA is solved
4. If the answer is correct, then complete the transaction
5. If the answer is incorrect, then send notification about an inaccurately solved CAPTCHA and complete the transaction.

Uploading CAPTCHA

You can upload your CAPTCHAs in two available formats:

multipart and base64.:

Multipad sample:

<form method="post" action="http://2captcha.com/in.php" enctype="multipart/form-data">
<input type="hidden" name="method" value="post">
Your key:
<input type="text" name="key" value="YOUR_APIKEY">
The CAPTCHA file:
<input type="file" name="file">
<input type="submit" value="download and get the ID">
</form>

 

YOUR_APIKEY - is your key of 32 symbols length.

Base64 Sample:

<form method="post" action="http://2captcha.com/in.php">
<input type="hidden" name="method" value="base64">
Your key:
<input type="text" name="key" value="YOUR_APIKEY">
The CAPTCHA file body in base64 format:
<textarea name="body">BASE64_FILE</textarea>
<input type="submit" value="download and get the ID">
</form>

YOUR_APIKEY - is your key of 32 symbols length.

BASE64_FILE - is the base 64 encoded image body.


Additional CAPTCHA parameters


 

POST parameter Possible values parameter description
phrase 0;1 0 = 1 word (default value)
1 = CAPTCHA contains 2 words
regsense 0;1 0 = not case sensitive (default value)
1 = case sensitive
numeric 0;1;2;3;4

0 = not specified (default value)
1 = captcha contains only numbers
2 = captcha contains only letters
3 = captcha contains only numbers OR only letters
4 = captcha contains both numbers AND letters

calc 0;1 0 = not specified (default value)
1 = math CAPTCHA (users are to perform calculation)
min_len 0..20

0 = not specified (default value)
1..20 = minimal number of symbols in the CAPTCHA text

max_len 1..20 0 = not specified (default value)
1..20 = maximal number of symbols in the CAPTCHA text
language 0;1;2

0 = not specified (default value)
1 = Cyrillic CAPTCHA
2 = Latin CAPTCHA

soft_id   Developer’s ID. Developers that integrate with 2Captcha.com get 10% from all CAPTCHAs that come from their software.
header_acao 0;1 0 = default value
1 = in.php for Access-Control-Allow-Origin: * response title parameter. (Used for cross-domaine AJAX requests in web applications, and for res.php.)
textinstructions TEXT this option is necessary to send text, no longer than 140 characters. The picture at the same time also need to be sent.
textinstructions TEXT send the text, no longer than 140 characters. You do not need to send a picture.
Pingback site.com/answer.php Pingback is a request you can use for the 2Captcha server that tells it to send your image to a given address, after it's been recognized.
id_construction NN Number of captcha-constructor

Server response to the uploaded CAPTCHA


 

Server response Status Meaning
OK|%CAPTCHA_ID%  accepted The CAPTHCA is put in the queue.
%CAPTCHA_ID% is CAPTCHA ID that you will need to request the CAPTCHA status
ERROR_WRONG_USER_KEY denied Wrong “key” parameter format, it should contain 32 symbols
ERROR_KEY_DOES_NOT_EXIST denied The “key” doesn’t exist
ERROR_ZERO_BALANCE denied You don’t have money on your account
ERROR_NO_SLOT_AVAILABLE denied This error can have two causes: 1) There is queue of captchas sent from your account which is exceedingly long and they haven’t been assigned to the workers yet. Maximal number of captchas in such queue from one account can be between 50 and 100, depending on the total number of captchas in the queue awaiting their assignment.
2) If you are sending regular captchas (as opposed to recaptchas) this error can happen if you have set your maximum rate lower than the current rate on the server.
P.S: This error became particularly substantial after we've added the new userrecaptch method, as it allows you to send hundreds of captchas in the space of one second. If you’ve got this error – make a one second pause and repeat your request.
ERROR_ZERO_CAPTCHA_FILESIZE denied CAPTCHA size is less than 100 bites
ERROR_TOO_BIG_CAPTCHA_FILESIZE denied CAPTCHA size is more than 100 Kbites
ERROR_WRONG_FILE_EXTENSION denied The CAPTCHA has a wrong extension. Possible extensions are: jpg,jpeg,gif,png
ERROR_IMAGE_TYPE_NOT_SUPPORTED denied The server cannot recognize the CAPTCHA file type.
ERROR_IP_NOT_ALLOWED denied The request has sent from the IP that is not on the list of your IPs. Check the list of your IPs in the system.
IP_BANNED denied The IP address you're trying to access our server with is banned due to many frequent attempts to access the server using wrong authorization keys. To lift the ban, please, contact our support team via email: support@2captcha.com
ERROR_CAPTCHAIMAGE_BLOCKED denied You have sent an image, that is unrecognizable and which is saved in our database as such. Usually this happens when the site where you get the captcha from has stopped sending you captcha and started giving you a “deny access” cap.

Getting the solved CAPTCHA


 

GET request

Use GET request of the following configuration:

http://2captcha.com/res.php?key=YOUR_APIKEY&action=get&id=CAPCHA_ID

YOUR_APIKEY - stands for you key 32 symbols length.
CAPTCHA_ID - stands for the ID of the previously uploaded CAPTCHA

Server response:

Server response to the status request Status Meaning
OK|%TEXT% done CAPTCHA solved successfully
%TEXT% - stands for the decoded text
CAPCHA_NOT_READY in progress CAPTCHA is being solved, repeat the request several seconds later
ERROR_KEY_DOES_NOT_EXIST error You used the wrong key in the query
ERROR_WRONG_ID_FORMAT error Wrong format ID CAPTCHA. ID must contain only numbers
ERROR_CAPTCHA_UNSOLVABLE error Three different employees were unable to solve Captcha. Funds for this captcha not be charged from your account.
ERROR_WRONG_CAPTCHA_ID error You are trying to get the answer or complain a captcha that was submitted more than 15 minutes ago.
ERROR_BAD_DUPLICATES error Error is returned when 100% accuracy feature is enabled. The error means that max numbers of tries is reached but min number of matches not found.
REPORT_NOT_RECORDED complain not accepted Error is returned to your complain request (reportbad) if you already complained lots of correctly solved captchas.

 

Automated answer returned form the POST server on request (pingback):

2Captcha.com offers functionality to reduce the number of requests you send to the server and still get your recognized image instantly after the CAPTCHA solver has typed in the answer. Here is how the process works:
1. Register an address to receive answers. It can be an IP address or an URL address. Please note that you can only register an address from the IP you will get answers to later. This means that you cannot register, for example, http://site.com/admin as your address for further notifications if you try to register it from IP 173.194.32.133
2. Send us your image with the additional parameter:
pingback=http://site.ru/answer.php
You can send the image from whatever address you want, but the pingback address has to be registered as described in point 1.
3. The image is recognized at 2Captcha server.
4. As soon as we get the answer, we send a POST request to your address in the following format:
CAPTCHA_ID,CODE
Adding IP:
http://2captcha.com/res.php?action=add_pingback&key=API_KEY&addr=127.0.0.1/test.php
Getting all addresses added for pingback:
http://2captcha.com/res.php?action=get_pingback&key=API_KEY
Deleting an address:
http://2captcha.com/res.php?action=del_pingback&key=YOUR_API_KEY&addr=127.0.0.1/test.php
Deleting all pingback addresses:
http://2captcha.com/res.php?action=del_pingback&key=YOUR_API_KEY&addr=all
Use the following parameter to tell the server where to send the answer to your image:
pingback="127.0.0.1/test.php"

Limitations and additional information about address registration:
1. You can add your pingback address from its own IP address only. If you want to receive answers to 127.0.0.1/answer, use IP 127.0.0.1 during the address registration.
2. You can add 100 addresses at max.
3. You can upload images from any IP you want, the answer will be returned to the address of your choice, if it has previously been properly registered and added to the list of your account addresses.
4. Different users can add same addresses, it doesn't lead to errors.

 

Additional API requests


 

Request Answer Meaning
action=get&ids=CAPTCHA_ID_1,CAPTCHA_ID_2,...,CAPTCHA_ID_N
 
%TEXT_1%|%TEXT_2%...%TEXT_N% Requests status for several CAPTCHAs. The solved text or the code CAPCHA_NOT_READY will be separated with the "|"
action=reportbad&id=CAPCHA_ID OK_REPORT_RECORDED Complain about the wrong CAPTCHA.
action=getbalance %BALANCE% Get your account balance. Your balance is in USD.
action=getstats&date=2013-11-27 %FILE.XML% Get your account statistics for the given period. You will get an XML file.
http://2captcha.com/load.php 5 88.3 0.014 14.965648650099 waiting: waiting: how many decoders are waiting for CAPTCHA.
load: how busy the decoders are, %
minbid: current bid for CAPTCHA solving, USD.
averageRecognitionTime: current average recognition time, seconds

reCAPTCHA 2.0 (click images that look alike)

reCAPTCHA is solved if the right parts of it are ticked. We added new parameters to 2Captcha in order for you to be able to send us relevant requests. General reCAPTCHA solving algorithm looks as follows:
1) You tick the initial reCAPTCHA box.
2) You are offered what looks like a set of images + instructions (what you need to do with this set). IRL it's one image that has a grid on it.
3) You send us the set the image along with the instructions (original images, the grid and the blue box are not needed).
4) You get the CAPTCHA ID from us.
5) We check the image set size. If it's 300x300px, we put a 3x3 grid on it. If the image set size is different, we put a 4x4 grid on it.
6) You make a request to give the solved reCAPTCHA from us 5 seconds later.
7) We tell you numbers of grid cells that you
Формат ответа:
OK|click:3/8/9/
It costs $1,2 to solve 1000 reCAPTCHAs this way.
Images are numbered starting from number 1, from left to right, from top to bottom.

Parametr Description
recaptcha=1 This parameter tells us that this specific CAPTCHA has to be processed as a reCAPTCHA. It's an important parameter, because it means that the image will get a 3x3 or a 4x4 grid upon it, and CAPTCHA solvers will further find the right cells to tick on that grid.
textinstructions=%TEXT% Here is the text of what needs to be ticked on the image. The text is to be in UTF-8 character set. This parameter isn't necessary, if you send imginstructions parameter.
imginstructions=img "img" is the image of the instructions. You can send it as multipart and base64. This parameter isn't necessary if you send textinstructions parameter.
recaptchacols=3
recaptcharows=3
Number of columns and number or rows in the incoming image. If you don't send those parameters, we put a default grid but in this case chances are the grid is wrong.

recaptcha=1 restrictions:
1. It cannot exceed 100 kB
2. imginstructions cannot exceed 25 kB
3. imginstructions cannot exceed 100x100 px
4. textinstructions cannot exceed 140 symbols

Please pay attention to the fact that reCAPTCHAs currently can be accepted if they are 3x3 or 4x4 cells only. In order to understand the number of cells on the image you've sent us, we check the image size in px. If it's 300x300 px, we put a 3x3 grid. If it's 400x400 px, we use a 4x4 grid. So please, don't combine this image with anything you like, just send it as it is.

Please note, that you need to send the reCAPTCHA image itself, not its screenshot.

How to Recognize Any ClickCAPTCHA Including reCAPTCHA 2.0

Main recognition pattern:
1. You send us your CAPTCHA image. You can send us text up to 140 symbols along with but not seamed with it.
2. CAPTCHA solvers click specific points of the image.
3. We return these points coordinates to you. The point where x=0 and y=0 is the left upper corner of the image.

Servers reply to this CAPTCHA looks the following way:
OK|coordinate:x=39,y=59;x=252,y=72
It costs $1,2 to recognize 1000 CAPTCHAs this way.

Parametr Description
coordinatescaptcha=1 This means that you are sending us a ClickCAPTCHA. In this way, the CAPTCHA solver won't be able to type an answer, they will need to click specific parts of the image with their mouse device.
textinstructions=%TEXT% Here is the text describing what needs to be chosen on the image. It can be put in UTF-8 characters set only so far. This parameter isn't necessary in case it's possible to understand where one should click on the image without explanation.

RotateCAPTCHA, FunCAPTCHA and other CAPTCHAs Where You Need to Rotate Image

Main recognition pattern:
1. You send us one or several images.
2. You tell us what angle the image should be rotated to, at each step (this parameter isn't obligatory).
3. We give CAPTCHA solver all the images you've sent to us. They see arrows next to each image. The image rotates when they click on them.
4. We give you back the right angle you need to rotate the image to in order to solve your CAPTCHA.

The answer you get to this CAPTCHA will look like:
OK|40|200|-120
Negative figure means that the image is to be rotated counter-clockwise.
Positive figure means that the image is to be rotated clockwise.

It costs $0.5 to solve 1000 CAPTCHAs this way.

Parametr Description
method=rotatecaptcha This means you are sending a CAPTCHA that needs to be rotated. The CAPTCHA solver won't be able to type an answer, they will need to click arrows in order to rotate the image.
angle=45 The angle you want the image to be rotated with each click on the arrow. If you don't use this parameter, the default angle is 40, as it is used by FunCaptcha.
file_1, file_2, file_3 Images that CAPTCHA solvers will rotate.

RotateCAPTCHA sample upload looks the following way:

<form method="post" action="http://rucaptcha.com/in.php" enctype="multipart/form-data">

KEY:<br>
<input  name="key" value="YOURKEY"><br>
Type<br>
<input  name="method" value="rotatecaptcha"><br>
Angle<br>
<input  name="angle" value="40"><br>


Files:<br>
<input type="file" name="file_1"><br>
<input type="file" name="file_2"><br>
<input type="file" name="file_3"><br>

Upload:<br>
<input type="submit" value="Upload and get ID">
</form>

 

Request Limits

Please remember and understand that each your request to our API generates multuple requests to our databases. Please set proper timeouts for your requests and use error handling for cases when server returns an error (error message, http error or html page with error).

For example if server returns ERROR_NO_SLOT_AVAILABLE make a 5 seconds timeout before sending next request. If server returns ERROR_ZERO_BALANCE set the timeout to 60 seconds.

After uploading a captcha wait a least 5 seconds (10-20 for recaptcha) and only then try to get the answer. If captcha is not solved yet - retry to get the answer after 5 seconds.

If your timeouts are configured incorrectly your account ir IP address will be temporary blocked and server will return an error. Descriptions of error codes are available in the table below.

 

Error codes list for account blocking

Error code Blocking time Blocking reason
ERROR: 1001 10 minutes You received 120 ERROR_NO_SLOT_AVAILABLE errors in one minute because your current bid is lower than current bid on the server
ERROR: 1002 5 minutes You received 120 ERROR_ZERO_BALANCE errors in one minute because your balance is out
ERROR: 1003 30 seconds You are getting ERROR_NO_SLOT_AVAILABLE because you are uploading many captchas and server has a long queue of your captchas that are not distributed to workers.
You received three times more errors than amount of captchas you sent (but not less than 120 errors). Increase the timeout if you see this error.
ERROR: 1004 10 minutes Your IP address is blocked because there were 5 requests with incorrect API key from your IP.
ERROR: 1005 5 minutes You are making too many requests to res.php to get answers.
We use the following rule to block your account: R > C * 20 + 1200
Where:
R - the amount of your requests
C - the amount of captchas you've uploaded
That means that you don't have to make more than 20 requests to res.php per each captcha.
Please remember that balance request sent to res.php also counts!

To get your answer faster without a risk to be blocked you can use pingback feature and we will send you the answer when your captcha is solved. For more info refer to: https://2captcha.com/api-2captcha#pingback