DeathByCaptcha API Clients
Introduction
DeathByCaptcha offers APIs of two types — HTTP and socket-based,
with the latter being recommended for having faster responses and overall
better performance. Switching between different APIs is usually as easy as
changing the client class and/or package name, the interface stays the same.
When using the socket API, please make sure that outgoing TCP traffic to
api.dbcapi.me to the ports range 8123–8130
is not blocked on your side.
How to Use DBC API Clients
Thread-safety notes
.NET, Java and Python clients are thread-safe,
means it is perfectly fine to share a client between multiple threads (although
in a heavily multithreaded applications it is a better idea to keep a pool of
clients).
PHP itself is not multithreaded so the clients are not thread-safe.
Perl clients are not thread-safe at this moment, use a client instance
per thread.
Common Clients' Interface
All the clients have to be instantiated with two string arguments: your
DeathByCaptcha account's username and password.
All the clients provide a few methods to handle your CAPTCHAs and your
DBC account. Below you will find those methods' short summary summary and
signatures in pseudo-code. Check the example scripts and the clients' source
code for more details.
Upload()
Uploads a CAPTCHA to the DBC service for solving, returns uploaded CAPTCHA details on success, NULL
otherwise. Here are the signatures in pseudo-code:
- .NET
DeathByCaptcha.Captcha DeathByCaptcha.Client.Upload(byte[] imageData)
DeathByCaptcha.Captcha DeathByCaptcha.Client.Upload(Stream imageStream)
DeathByCaptcha.Captcha DeathByCaptcha.Client.Upload(string imageFileName)
- Java
com.DeathByCaptcha.Captcha com.DeathByCaptcha.Client.upload(byte[] imageData)
com.DeathByCaptcha.Captcha com.DeathByCaptcha.Client.upload(InputStream imageStream)
com.DeathByCaptcha.Captcha com.DeathByCaptcha.Client.upload(File imageFile)
com.DeathByCaptcha.Captcha com.DeathByCaptcha.Client.upload(String imageFileName)
- Perl
hash DeathByCaptcha.Client->upload(string $imageFileName)
- PHP
array DeathByCaptcha_Client->upload(resource $imageFile)
array DeathByCaptcha_Client->upload(string $imageFileName)
- Python
dict deathbycaptcha.Client.upload(file imageFile)
dict deathbycaptcha.Client.upload(str imageFileName)
GetCaptcha()
Fetches uploaded CAPTCHA details, returns NULL
on failures.
- .NET
DeathByCaptcha.Captcha DeathByCaptcha.Client.GetCaptcha(int captchaId)
DeathByCaptcha.Captcha DeathByCaptcha.Client.GetCaptcha(DeathByCaptcha.Captcha captcha)
- Java
com.DeathByCaptcha.Captcha com.DeathByCaptcha.Client.getCaptcha(int captchaId)
com.DeathByCaptcha.Captcha com.DeathByCaptcha.Client.getCaptcha(com.DeathByCaptcha.Captcha captcha)
- Perl
hash DeathByCaptcha.Client->getCaptcha(int $captchaId)
- PHP
array DeathByCaptcha_Client->get_captcha(int $captchaId)
- Python
dict deathbycaptcha.Client.get_captcha(dict imageFileName)
Report()
Reports incorrectly solved CAPTCHA for refund, returns true
on success, false
otherwise.
Please make sure the CAPTCHA you're reporting was in fact incorrectly solved, do not just report them thoughtlessly, or else you'll be flagged as abuser and banned.
- .NET
bool DeathByCaptcha.Client.Report(int captchaId)
bool DeathByCaptcha.Client.Report(DeathByCaptcha.Captcha captcha)
- Java
boolean com.DeathByCaptcha.Client.report(int captchaId)
boolean com.DeathByCaptcha.Client.report(com.DeathByCaptcha.Captcha captcha)
- Perl
bool DeathByCaptcha.Client->report(int $captchaId)
- PHP
bool DeathByCaptcha.Client->report(int $captchaId)
- Python
bool deathbycaptcha.Client.report(int captchaId)
Decode()
This method uploads a CAPTCHA, then polls for its status until it's solved or times out; returns solved CAPTCHA details on success, NULL
otherwise.
- .NET
DeathByCaptcha.Captcha DeathByCaptcha.Client.Decode(byte[] imageData, int timeout)
DeathByCaptcha.Captcha DeathByCaptcha.Client.Decode(Stream imageStream, int timeout)
DeathByCaptcha.Captcha DeathByCaptcha.Client.Decode(string imageFileName, int timeout)
- Java
com.DeathByCaptcha.Captcha com.DeathByCaptcha.Client.decode(byte[] imageData, int timeout)
com.DeathByCaptcha.Captcha com.DeathByCaptcha.Client.decode(InputStream imageStream, int timeout)
com.DeathByCaptcha.Captcha com.DeathByCaptcha.Client.decode(File imageFile, int timeout)
com.DeathByCaptcha.Captcha com.DeathByCaptcha.Client.decode(string imageFileName, int timeout)
- Perl
hash DeathByCaptcha.Client->decode(string $imageFileName, int $timeout)
- PHP
array DeathByCaptcha.Client->decode(resource $imageFile, int $timeout)
array DeathByCaptcha.Client->decode(string $imageFileName, int $timeout)
- Python
dict deathbycaptcha.Client.decode(file imageFile, int timeout)
dict deathbycaptcha.Client.decode(str imageFileName, int timeout)
GetBalance()
Fetches your current DBC credit balance (in US cents).
- .NET
double DeathByCaptcha.Client.GetBalance()
- Java
double com.DeathByCaptcha.Client.getBalance()
- Perl
float DeathByCaptcha.Client->getBalance()
- PHP
float DeathByCaptcha.Client->get_balance()
- Python
float deathbycaptcha.Client.get_balance()
CAPTCHA objects/details hashes
.NET and Java clients wrap CAPTCHA details in DeathByCaptcha.Captcha
and com.DeathByCaptcha.Captcha
objects respectively, exposing CAPTCHA details through the following properties and methods:
- CAPTCHA numeric ID as integer
Id
(.NET) and id
(Java) properties;
- CAPTCHA text as string
Text
(.NET) and text
(Java) properties;
- a flag showing whether the CAPTCHA was uploaded, as boolean
Uploaded
property (.NET) and isUploaded()
(Java) method;
- a flag showing whether the CAPTCHA was solved, as boolean
Solved
property (.NET) and isSolved()
(Java) method;
- a flag showing whether the CAPTCHA was solved correctly, as boolean
Correct
property (.NET) and isCorrect()
(Java) method.
Clients in other languages use simple hashes (dictionaries, associative arrays etc.) to store CAPTCHA details, keeping numeric IDs under "captcha"
key, CAPTCHA text under "text"
key, and the correctness flag under "is_correct"
key.
Examples
Below you can find a few DBC API clients' usage examples.
C#
using DeathByCaptcha;
/* Put your DeathByCaptcha 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);
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 DBC API denied, check your credentials and/or balance */
}
Java
import com.DeathByCaptcha.AccessDeniedException;
import com.DeathByCaptcha.Captcha;
import com.DeathByCaptcha.Client;
import com.DeathByCaptcha.SocketClient;
import com.DeathByCaptcha.HttpClient;
/* Put your DeathByCaptcha 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 input stream,
or an array of bytes, and optional solving timeout (in seconds) here: */
Captcha captcha = client.decode(captchaFileName, timeout);
if (null != captcha) {
/* The CAPTCHA was solved; captcha.id property holds its numeric ID,
and captcha.text holds its text. */
System.out.println("CAPTCHA " + captcha.id + " solved: " + captcha.text);
if (/* check if the CAPTCHA was incorrectly solved */) {
client.report(captcha);
}
}
} catch (AccessDeniedException e) {
/* Access to DBC API denied, check your credentials and/or balance */
}
PHP
require_once "deathbycaptcha.php";
/* Put your DBC account username and password here.
Use DeathByCaptcha_HttpClient for HTTP API. */
$client = new DeathByCaptcha_SocketClient($username, $password);
try {
$balance = $client->get_balance();
/* Put your CAPTCHA file name or opened file handler, and optional
solving timeout (in seconds) here: */
$captcha = $client->decode($captcha_file_name, $timeout);
if ($captcha) {
/* The CAPTCHA was solved; captcha["captcha"] item holds its
numeric ID, and captcha["text"] item its text. */
echo "CAPTCHA {$captcha["captcha"]} solved: {$captcha["text"]}";
if (/* check if the CAPTCHA was incorrectly solved */) {
$client->report($captcha["captcha"]);
}
}
} catch (DeathByCaptcha_AccessDeniedException) {
/* Access to DBC API denied, check your credentials and/or balance */
}
Python
import deathbycaptcha
# Put your DBC account username and password here.
# Use deathbycaptcha.HttpClient for HTTP API.
client = deathbycaptcha.SocketClient(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_name, timeout)
if captcha:
# The CAPTCHA was solved; captcha["captcha"] item holds its
# numeric ID, and captcha["text"] item its text.
print "CAPTCHA %s solved: %s" % (captcha["captcha"], captcha["text"])
if ...: # check if the CAPTCHA was incorrectly solved
client.report(captcha["captcha"])
except deathbycaptcha.AccessDeniedException:
# Access to DBC API denied, check your credentials and/or balance
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 New Recaptcha API 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.
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.dbcapi.me/api/captcha
- What are the POST parameters for the Coordinates API?
-
- username: Your DBC account username
- password: Your DBC 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.dbcapi.me/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.dbcapi.me/api/captcha
- What are the POST parameters for the Image Group API?
-
- username: Your DBC account username
- password: Your DBC account password
- captchafile: the Base64 encoded file contents with a valid New Recaptcha screenshot.
You must send each image in a single "captchafile" parameter. The order you send them matters
- 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, dbc 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.dbcapi.me/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
Examples
Python and Recaptcha Coordinates API
import deathbycaptcha
# Put your DBC account username and password here.
username = "user"
password = "password"
captcha_file = 'test.jpg' # image
client = deathbycaptcha.SocketClient(username, password)
# to use http client use: client = deathbycaptcha.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 deathbycaptcha.AccessDeniedException:
# Access to DBC API denied, check your credentials and/or balance
print "error: Access to DBC API denied, check your credentials and/or balance"
Python and Recaptcha Image Group
import deathbycaptcha
# Put your DBC 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 = deathbycaptcha.SocketClient(username, password)
client = deathbycaptcha.HttpClient(username, password)
# to use http client use: client = deathbycaptcha.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)
#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_file, type=3, banner=banner, banner_text=banner_text, grid="2x4")
#see 2x4.png example image to have an idea what that images look like
#If you wont supply `grid` argument, dbc will attempt to autodetect the 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 deathbycaptcha.AccessDeniedException:
# Access to DBC API denied, check your credentials and/or balance
print "error: Access to DBC API denied, check your credentials and/or balance"
PHP and Recaptcha Coordinates API
/**
* Death by Captcha PHP API recaptcha coordinates usage example
*
* @package DBCAPI
* @subpackage PHP
*/
/**
* DBC API clients
*/
require_once 'deathbycaptcha.php';
// Put your DBC username & password here.
$username = "username";
$password = "password";
$captcha_filename = "test.jpg"; # your captchafile
$extra = ['type'=>2]; # extra parameters in an array
// Use DeathByCaptcha_HttpClient() class if you want to use HTTP API.
$client = new DeathByCaptcha_SocketClient($username, $password);
$client->is_verbose = true;
echo "Your balance is {$client->balance} US cents\n";
// Put your CAPTCHA image file name, file resource, or vector of bytes,
// and optional solving timeout (in seconds) here; you'll get CAPTCHA
// details array on success.
if ($captcha = $client->decode($captcha_filename, $extra)) {
echo "CAPTCHA {$captcha['captcha']} uploaded\n";
sleep(DeathByCaptcha_Client::DEFAULT_TIMEOUT);
// Poll for CAPTCHA coordinates:
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']);
}
}
PHP and Recaptcha Image Group
/**
* Death by Captcha PHP API recaptcha coordinates usage example
*
* @package DBCAPI
* @subpackage PHP
*/
/**
* DBC API clients
*/
require_once 'deathbycaptcha.php';
// Put your DBC 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
#'grid' => "3x2" #optional paramater for specifying what grid
#images are aligned to.
#If ommitted, dbc would try to autodetect the grid.
];
// Use DeathByCaptcha_HttpClient() class if you want to use HTTP API.
$client = new DeathByCaptcha_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(DeathByCaptcha_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']);
}
}