Download the api client based example codes:
New Recaptcha API support
What's "new reCAPTCHA/noCAPTCHA"?
They're new reCAPTCHA challenges that typically require the user to identify and click on certain images. They're not to be confused with traditional word/number reCAPTCHAs (those have no images).
For your convinience, we implemented support for New Recaptcha API. If your software works with it, and supports minimal configuration, you should be able to decode captchas using ImagesToText in no time.
We provide two different types of New Recaptcha API:
- Coordinates API: Provided a screenshot, the API returns a group of coordinates to click.
- Image Group API: Provided a group of (base64-encoded) images, the API returns the indexes of the images to click.
Pricing
For the time being, price is 3.99/1k new reCAPTCHA challenges correctly solved. You will not be billed for images reported as incorrectly solved. Note that this pricing applies to new reCAPTCHA / noCAPTCHA images only, so only customers using this specific API will be charged above rate.
Image upload restrictions.
Image file size is limited to less than 180 KB. When the image will be encoded in base64, the size should be lower than 120 KB. The supported image formats are JPG, PNG, GIF and BMP.
Coordinates API FAQ:
- What's the Coordinates API URL?
-
To use the Coordinates API you will have to send a HTTP POST Request to http://api.imagestotext.com/api/captcha
- What are the POST parameters for the Coordinates API?
-
These are:
- username: Your ITT account username
- password: Your ITT account password
- captchafile: a Base64 encoded or Multipart file contents with a valid New Recaptcha screenshot
- type=2: Type 2 specifies this is a New Recaptcha Coordinates API
- What's the response from the Coordinates API?
-
captcha: id of the provided captcha, if the text field is null, you will have to pool the url http://api.imagestotext.com/api/captcha/captcha_id until it becomes available
is_correct:(0 or 1) specifying if the captcha was marked as incorrect or unreadable
text: a json-like nested list, with all the coordinates (x, y) to click relative to the image, for example:
[[23.21, 82.11]]where the X coordinate is 23.21 and the Y coordinate is 82.11
Image Group API FAQ:
- What's the Image Group API URL?
-
To use the Image Group API you will have to send a HTTP POST Request to http://api.imagestotext.com/api/captcha
- What are the POST parameters for the Image Group API?
-
These are:
- username: Your ITT account username
- password: Your ITT account password
- captchafile: the Base64 encoded file/image contents with the valid New Recaptcha.
- banner: the Base64 encoded banner image (the example image that appears on the upper right)
- banner_text: the banner text (the text that appears on the upper left)
- type=3: Type 3 specifies this is a New Recaptcha Image Group API
- grid: Optional grid parameter specifies what grid individual images in captcha are aligned to (string, width+"x"+height, Ex.: "2x4", if images aligned to 4 rows with 2 images in each. If not supplied, itt will attempt to autodetect the grid.
- What's the response from the Image Group API?
-
captcha: id of the provided captcha, if the text field is null, you will have to pool the url http://api.imagestotext.com/api/captcha/captcha_id until it becomes available
is_correct:(0 or 1) specifying if the captcha was marked as incorrect or unreadable
text: a json-like list of the index for each image that should be clicked. for example:
[1, 4, 6]where the images that should be clicked are the first, the fourth and the six, counting from left to right and up to bottom
Usage code examples for COORDINATES API and IMAGE GROUP API:
1) Send your image:
Please note we are using type="2" for CAPTCHA COORDINATES API.
curl --header 'Expect: ' -F username=your_username_here \
-F password=your_password_here \
-F captchafile=@'your_captcha_filename.jpg' \
-F type='2' http://api.imagestotext.com/api/captcha
OR:
Please note we are using type="3" for CAPTCHA IMAGE GROUP API.
curl --header 'Expect: ' -F username=your_username_here \
-F password=your_password_here \
-F captchafile=@'your_captcha_filename.jpg' \
-F banner=@'your_banner_filename.jpg' \
-F banner_text=banner_text_here \
-F type='3' http://api.imagestotext.com/api/captcha
Or, if you are supplying grid info (height x width). In this example grid 4x2 is used, you should specify it according to uploaded image. If you wont supply grid parameter, itt would attempt to autodetect proper grid.
curl --header 'Expect: ' -F username=your_username_here \
-F password=your_password_here \
-F captchafile=@'your_captcha_filename.jpg' \
-F banner=@'your_banner_filename.jpg' \
-F banner_text=banner_text_here \
-F type='3' http://api.imagestotext.com/api/captcha
-F grid=4x2
Result is an url_encoded data including the respective CAPTCHA_ID:
'status=0&captcha=CAPTCHA_ID&text=&is_correct=1'2) Pulling captcha coordinates: take the given CAPTCHA_ID and make a request like this:
curl -H "Accept: application/json" \
http://api.imagestotext.com/api/captcha/CAPTCHA_IDResult is a json-string where the field "text" includes the respective coords:
'{"status": 0, "captcha": 2911096,
"is_correct": true, "text": "[[57,240],[156,335]"}'Using COORDINATES API and IMAGE GROUP API with api clients:
1) PHP
/**
* Images To Text PHP API recaptcha coordinates usage example
*
* @package ITTAPI
* @subpackage PHP
*/
/**
* ITT API clients
*/
require_once 'imagestotext.php';
// Put your ITT username & password here.
$username = "username";
$password = "password";
$captcha_filename = "test2.jpg"; # your captchafile
// extra parameters in an array
$extra = [
'type'=>3,
'banner'=> 'banner.jpg', # banner img
'banner_text'=> "select all pizza:" # banner text
# if you want to supply grid information (height x width)
#'grid' => "4x2"
# In this example grid 4x2 is used, you should specify it
# according to uploaded image.
# If you wont supply grid parameter, itt would attempt to
# autodetect proper grid.
];
// Use ImagesToText_HttpClient() class if you want to use HTTP API.
$client = new ImagesToText_SocketClient($username, $password);
$client->is_verbose = true;
echo "Your balance is {$client->balance} US cents\n";
if ($captcha = $client->decode($captcha_filename, $extra)) {
echo "CAPTCHA {$captcha['captcha']} uploaded\n";
sleep(ImagesToText_Client::DEFAULT_TIMEOUT);
// Poll for CAPTCHA indexes:
if ($text = $client->get_text($captcha['captcha'])) {
echo "CAPTCHA {$captcha['captcha']} solved: {$text}\n";
// Report an incorrectly solved CAPTCHA.
// Make sure the CAPTCHA was in fact incorrectly solved!
//$client->report($captcha['captcha']);
}
}
2) PYTHON>
RECAPTCHA COORDINATES
import imagestotext
# Put your ITT account username and password here.
username = "user"
password = "password"
captcha_file = 'test.jpg' # image
client = imagestotext.SocketClient(username, password)
# to use http client use:
# client = imagestotext.HttpClient(username, password)
try:
balance = client.get_balance()
# Put your CAPTCHA file name or file-like object, and optional
# solving timeout (in seconds) here:
captcha = client.decode(captcha_file, type=2)
if captcha:
# The CAPTCHA was solved; captcha["captcha"] item holds its
# numeric ID, and captcha["text"] item its list of "coordinates".
print "CAPTCHA %s solved: %s" % (
captcha["captcha"], captcha["text"])
if '': # check if the CAPTCHA was incorrectly solved
client.report(captcha["captcha"])
except imagestotext.AccessDeniedException:
# Access to ITT API denied, check your credentials and/or balance
print "error: Access to ITT API denied, check your credentials and/or balance"
RECAPTCHA IMAGE GROUP
import imagestotext
# Put your ITT account username and password here.
username = "user"
password = "password"
captcha_file = "test2.jpg" # image
banner = "banner.jpg" # image banner
banner_text = "select all pizza:"
client = imagestotext.SocketClient(username, password)
# to use http client use:
# client = imagestotext.HttpClient(username, password)
try:
balance = client.get_balance()
# Put your CAPTCHA file name or file-like object, and optional
# solving timeout (in seconds) here:
captcha = client.decode(
captcha_file, type=3, banner=banner, banner_text=banner_text)
# if you are supplying grid information, it should be
# something like this:
#
# captcha = client.decode(
# captcha_file, type=3, banner=banner,
# banner_text=banner_text, grid="4x2")
#
# In this example grid 4x2 is used, you should specify it
# according to uploaded image.
# If you wont supply grid parameter, itt would attempt to
# autodetect proper grid.
if captcha:
# The CAPTCHA was solved; captcha["captcha"] item holds its
# numeric ID, and captcha["text"] is a json-like list
# of the index for each image that should be clicked.
print "CAPTCHA %s solved: %s" % (
captcha["captcha"], captcha["text"])
if '': # check if the CAPTCHA was incorrectly solved
client.report(captcha["captcha"])
except imagestotext.AccessDeniedException:
# Access to ITT API denied, check your credentials and/or balance
print "error: Access to ITT API denied, check your credentials and/or balance"
3) JAVA
import com.ImagesToText.AccessDeniedException;
import com.ImagesToText.Client;
import com.ImagesToText.HttpClient;
import com.ImagesToText.SocketClient;
import com.ImagesToText.Captcha;
import java.io.IOException;
class ExampleNewRecaptcha
{
public static void main(String[] args)
throws Exception
{
// EXAMPLE RECAPTCHA_COORDINATES.
// Put your ITT username & password here:
//Client client = (Client)(new HttpClient(args[0], args[1]));
String username = "your_username_here";
String password = "your_password_here";
String filename = "test.jpg";
Client client = (Client)(new SocketClient(username, password));
client.isVerbose = true;
try {
try {
System.out.println(
"Your balance is " + client.getBalance()
+ " US cents");
} catch (IOException e) {
System.out.println("Failed fetching balance: "
+ e.toString());
return;
}
Captcha captcha = null;
try {
// Upload a CAPTCHA and poll for its status with 120
// seconds timeout.
// Put you CAPTCHA image file name, file object,
// input stream, or vector of bytes, and solving
// timeout (in seconds).
// If 0 then the default value take place.
// Please note we are specifying type=2 in the
// second argument.
captcha = client.decode(filename, 2, 0);
} catch (IOException e) {
System.out.println("Failed uploading CAPTCHA");
return;
}
if (null != captcha) {
System.out.println(
"CAPTCHA " + captcha.id + " solved: " + captcha.text);
// Report incorrectly solved CAPTCHA if necessary.
// Make sure you've checked if the CAPTCHA was in
// fact incorrectly solved, or else you might get
// banned as abuser.
/*try {
if (client.report(captcha)) {
System.out.println(
"Reported as incorrectly solved");
} else {
System.out.println(
"Failed reporting incorrectly solved CAPTCHA");
}
} catch (IOException e) {
System.out.println(
"Failed reporting incorrectly solved CAPTCHA: "
+ e.toString());
}*/
} else {
System.out.println("Failed solving CAPTCHA");
}
} catch (com.ImagesToText.Exception e) {
System.out.println(e);
}
// EXAMPLE RECAPTCHA_IMAGE_GROUP.
// Put your ITT username & password here:
//Client client = (Client)(new HttpClient(args[0], args[1]));
filename = "test2.jpg";
String banner = "banner.jpg";
String banner_text = "choose all pizza:";
try {
try {
System.out.println("Your balance is " + client.getBalance()
+ " US cents");
} catch (IOException e) {
System.out.println("Failed fetching balance: "
+ e.toString());
return;
}
Captcha captcha = null;
try {
// Upload a CAPTCHA and poll for its status with
// 120 seconds timeout.
// Put you CAPTCHA image file name, file object,
// input stream, or vector of bytes, and solving
// timeout (in seconds).
// If 0 then the default value take place.
// Please note we are specifying banner, banner_test and
// type=3 in the second argument.
captcha = client.decode(filename, 3, banner, banner_text, 0);
// For adding grid info, use call like this:
// captcha = client.decode(
// filename, 3, banner, banner_text, "4x2", 0);
// In this example grid 4x2 is used, you should specify
// it according to uploaded image.
// If you wont supply grid parameter, itt would attempt
// to autodetect proper grid.
} catch (IOException e) {
System.out.println("Failed uploading CAPTCHA");
return;
}
if (null != captcha) {
System.out.println(
"CAPTCHA " + captcha.id + " solved: " + captcha.text);
// Report incorrectly solved CAPTCHA if necessary.
// Make sure you've checked if the CAPTCHA was in fact
// incorrectly solved, or else you might get banned as abuser.
/*try {
if (client.report(captcha)) {
System.out.println("Reported as incorrectly solved");
} else {
System.out.println(
"Failed reporting incorrectly solved CAPTCHA");
}
} catch (IOException e) {
System.out.println(
"Failed reporting incorrectly solved CAPTCHA: "
+ e.toString());
}*/
} else {
System.out.println("Failed solving CAPTCHA");
}
} catch (com.ImagesToText.Exception e) {
System.out.println(e);
}
}
}
4) C# .Net
using ImagesToText;
/* Put your ImagesToText account username and password here.
Use HttpClient for HTTP API. */
Client client = (Client)new SocketClient(username, password);
try {
double balance = client.GetBalance();
/* Put your CAPTCHA file name, or file object,
or arbitrary stream, or an array of bytes,
and optional solving timeout (in seconds) here:
*/
Captcha captcha = client.Decode(captchaFileName, timeout);
/*
//Uploading captchas with type = 2 (Coordinates API)
Captcha captcha = client.Decode(captchaFileName, timeout,
new Hashtable (){
{ "type", 2 }
});
*/
/*
//Uploading captchas with type = 3 (Image Group API)
Captcha captcha = client.Decode(captchaFileName, timeout,
new Hashtable (){
{ "type", 3 },
{"banner_text", "Select all images with meat"},
{"banner", bannerFileName}
// if you want to specify grid data
//{"grid", "4x2"}
// In this example grid 4x2 is used, you should specify it
// according to uploaded image.
// If you wont supply grid parameter, itt would attempt to
// autodetect proper grid.
});
*/
if (null != captcha) {
/* The CAPTCHA was solved; captcha.Id property holds
its numeric ID, and captcha.Text holds its text. */
Console.WriteLine("CAPTCHA {0} solved: {1}", captcha.Id,
captcha.Text);
if (/* check if the CAPTCHA was incorrectly solved */) {
client.Report(captcha);
}
}
} catch (AccessDeniedException e) {
/* Access to ITT API denied, check your credentials and/or balance */
}
5) VB.Net
Imports ImagesToText
' Put your ITT username & password here:
' Dim clnt As New HttpClient(username, password)
Dim clnt As New SocketClient(username, password)
Console.WriteLine(String.Format("Your balance is {0,2:f} US cents",
clnt.Balance))
' Uploading captchas with type = 2 (Coordinates API)
' Dim ext_data As New Hashtable()
' ext_data.Add("type", 2)
' Put your CAPTCHA image file name, file object, stream, or vector
' of bytes, and optional solving timeout (in seconds) here:
' Dim cptch As Captcha = clnt.Decode(
' args(2), 2 * Client.DefaultTimeout, ext_data)
' Uploading captchas with type = 3 (Image Group API)
' Dim ext_data As New Hashtable()
' ext_data.Add("type", 3)
' ext_data.Add("banner_text", "Select all images with meat")
' ext_data.Add("banner", bannerFileName)
' if you want to add grid info
' ext_data.Add("grid", "4x2")
' In this example grid 4x2 is used, you should specify it according
' to uploaded image.
' If you wont supply grid parameter, itt would attempt to
' autodetect proper grid.
' Put your CAPTCHA image file name, file object, stream, or vector
' of bytes, and optional solving timeout (in seconds) here:
' Dim cptch As Captcha = clnt.Decode(
' args(2), 2 * Client.DefaultTimeout, ext_data)
' Put your CAPTCHA image file name, file object, stream, or vector
' of bytes, and optional solving timeout (in seconds) here:
Dim cptch As Captcha = clnt.Decode(args(2), 2 * Client.DefaultTimeout)
If cptch IsNot Nothing Then
Console.WriteLine(String.Format("CAPTCHA {0:d} solved: {1}", cptch.Id,
cptch.Text))
' Report an incorrectly solved CAPTCHA.
' Make sure the CAPTCHA was in fact incorrectly solved, do not
' just report it at random, or you might be banned as abuser.
'If clnt.Report(cptch) Then
' Console.WriteLine("Reported as incorrectly solved")
'Else
' Console.WriteLine("Failed reporting as incorrectly solved")
'End If
End If
6) iMacros
RECAPTCHA COORDINATES
VERSION BUILD=844
URL GOTO=http://api.imagestotext.com/decaptcher?function=picture2&print_format=html
TAG POS=1 TYPE=INPUT:TEXT FORM=ACTION:http://api.imagestotext.com/decaptcher ATTR=NAME:username CONTENT={{YOUR_ITT_USERNAME}}
TAG POS=1 TYPE=INPUT:TEXT FORM=ACTION:http://api.imagestotext.com/decaptcher ATTR=NAME:password CONTENT={{YOUR_ITT_PASSWORD}}
TAG POS=1 TYPE=INPUT:FILE FORM=ACTION:http://api.imagestotext.com/decaptcher ATTR=NAME:pict CONTENT={{PATH_TO_FILE}}
TAG POS=1 TYPE=INPUT:TEXT FORM=ACTION:http://api.imagestotext.com/decaptcher ATTR=NAME:pict_type CONTENT=2
TAG POS=1 TYPE=INPUT:SUBMIT FORM=ACTION:http://api.imagestotext.com/decaptcher ATTR=*
TAG POS=6 TYPE=TD ATTR=* EXTRACT=TXT
SET !VAR1 {{!EXTRACT}}
RECAPTCHA IMAGE GROUP
VERSION BUILD=844
URL GOTO=http://api.imagestotext.com/decaptcher?function=imagegroup&print_format=html
TAG POS=1 TYPE=INPUT:TEXT FORM=ACTION:http://api.imagestotext.com/decaptcher ATTR=NAME:username CONTENT={{YOUR_ITT_USERNAME}}
TAG POS=1 TYPE=INPUT:TEXT FORM=ACTION:http://api.imagestotext.com/decaptcher ATTR=NAME:password CONTENT={{YOUR_ITT_PASSWORD}}
TAG POS=1 TYPE=INPUT:FILE FORM=ACTION:http://api.imagestotext.com/decaptcher ATTR=NAME:pict CONTENT={{PATH_TO_MAIN_IMAGE}}
TAG POS=1 TYPE=INPUT:FILE FORM=ACTION:http://api.imagestotext.com/decaptcher ATTR=NAME:banner CONTENT={{PATH_TO_BANNER_IMAGE}}
TAG POS=1 TYPE=INPUT:TEXT FORM=ACTION:http://api.imagestotext.com/decaptcher ATTR=NAME:banner_text CONTENT={{BANNER_TEXT}}
TAG POS=1 TYPE=INPUT:TEXT FORM=ACTION:http://api.imagestotext.com/decaptcher ATTR=NAME:grid CONTENT={{GRID}}
TAG POS=1 TYPE=INPUT:SUBMIT FORM=ACTION:http://api.imagestotext.com/decaptcher ATTR=*
TAG POS=6 TYPE=TD ATTR=* EXTRACT=TXT
SET !VAR1 {{!EXTRACT}}
7) Node.js
RECAPTCHA COORDINATES
/*
* Images To Text Node.js API recaptcha coordinates usage example
*/
const itt = require('./imagestotext.js');
const username = 'username'; // ITT account username
const password = 'password'; // ITT account password
const captcha_file = 'test.jpg'; // Image filename
const client = new itt.SocketClient(username, password);
// const client = new itt.HttpClient(username, password) for http client
// Get user balance
client.get_balance((balance) => {
console.log(balance);
});
// Solve captcha with type 2 extra argument
client.decode({captcha: captcha_file, extra: {type: 2}}, (captcha) => {
if (captcha) {
console.log('Captcha ' + captcha['captcha'] + ' solved: ' + captcha['text']);
/*
* Report an incorrectly solved CAPTCHA.
* Make sure the CAPTCHA was in fact incorrectly solved!
* client.report(captcha['captcha'], (result) => {
* console.log('Report status: ' + result);
* });
*/
};
});
RECAPTCHA IMAGE GROUP
/*
* Images To Text Node.js API recaptcha image_group usage example
*/
const itt = require('./imagestotext.js');
const username = 'username'; // ITT account username
const password = 'password'; // ITT account password
const captcha_file = 'test2.jpg'; // Captcha image filename
const banner = 'banner.jpg'; // Banner image filename
const banner_text = 'select all pizza:'; // Banner text
// Images To Text Socket Client
const client = new itt.SocketClient(username, password);
// const client = new itt.HttpClient(username, password) for http client
// Get user balance
client.get_balance((balance) => {
console.log(balance);
});
// Solve captcha with type 3, banner & banner_text extra arguments
client.decode({captcha: captcha_file, extra: {type: 3, banner: banner, banner_text: banner_text}}, (captcha) => {
/*
* you can supply optional `grid` argument to decode() call, with a
* string like 3x3 or 2x4, defining what grid individual images were located at
* example:
* captcha = client.decode({captcha: captcha_file, extra: {type: 3, banner: banner, banner_text: banner_text, grid: "2x4"}}, (captcha) => {
* ...
* });
* see 2x4.png example image to have an idea what that images look like
* If you wont supply `grid` argument, itt will attempt to autodetect the grid
*/
if (captcha) {
console.log('Captcha ' + captcha['captcha'] + ' solved: ' + captcha['text']);
/*
* Report an incorrectly solved CAPTCHA.
* Make sure the CAPTCHA was in fact incorrectly solved!
* client.report(captcha['captcha'], (result) => {
* console.log('Report status: ' + result);
* });
*/
}
});
