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.deathbycaptcha.com 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