ImagesToText API Clients

Introduction

ImagesToText 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.imagestotext.com to the ports range 8123–8130 is not blocked on your side.

How to Use ITT 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 ImagesToText account's username and password.

All the clients provide a few methods to handle your CAPTCHAs and your ITT 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 ITT service for solving, returns uploaded CAPTCHA details on success, NULL otherwise. Here are the signatures in pseudo-code:

.NET
ImagesToText.Captcha ImagesToText.Client.Upload(byte[] imageData)
ImagesToText.Captcha ImagesToText.Client.Upload(Stream imageStream)
ImagesToText.Captcha ImagesToText.Client.Upload(string imageFileName)
Java
com.ImagesToText.Captcha com.ImagesToText.Client.upload(byte[] imageData)
com.ImagesToText.Captcha com.ImagesToText.Client.upload(InputStream imageStream)
com.ImagesToText.Captcha com.ImagesToText.Client.upload(File imageFile)
com.ImagesToText.Captcha com.ImagesToText.Client.upload(String imageFileName)
Perl
hash ImagesToText.Client->upload(string $imageFileName)
PHP
array ImagesToText_Client->upload(resource $imageFile)
array ImagesToText_Client->upload(string $imageFileName)
Python
dict imagestotext.Client.upload(file imageFile)
dict imagestotext.Client.upload(str imageFileName)

GetCaptcha()

Fetches uploaded CAPTCHA details, returns NULL on failures.

.NET
ImagesToText.Captcha ImagesToText.Client.GetCaptcha(int captchaId)
ImagesToText.Captcha ImagesToText.Client.GetCaptcha(ImagesToText.Captcha captcha)
Java
com.ImagesToText.Captcha com.ImagesToText.Client.getCaptcha(int captchaId)
com.ImagesToText.Captcha com.ImagesToText.Client.getCaptcha(com.ImagesToText.Captcha captcha)
Perl
hash ImagesToText.Client->getCaptcha(int $captchaId)
PHP
array ImagesToText_Client->get_captcha(int $captchaId)
Python
dict imagestotext.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 ImagesToText.Client.Report(int captchaId)
bool ImagesToText.Client.Report(ImagesToText.Captcha captcha)
Java
boolean com.ImagesToText.Client.report(int captchaId)
boolean com.ImagesToText.Client.report(com.ImagesToText.Captcha captcha)
Perl
bool ImagesToText.Client->report(int $captchaId)
PHP
bool ImagesToText.Client->report(int $captchaId)
Python
bool imagestotext.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
ImagesToText.Captcha ImagesToText.Client.Decode(byte[] imageData, int timeout)
ImagesToText.Captcha ImagesToText.Client.Decode(Stream imageStream, int timeout)
ImagesToText.Captcha ImagesToText.Client.Decode(string imageFileName, int timeout)
Java
com.ImagesToText.Captcha com.ImagesToText.Client.decode(byte[] imageData, int timeout)
com.ImagesToText.Captcha com.ImagesToText.Client.decode(InputStream imageStream, int timeout)
com.ImagesToText.Captcha com.ImagesToText.Client.decode(File imageFile, int timeout)
com.ImagesToText.Captcha com.ImagesToText.Client.decode(string imageFileName, int timeout)
Perl
hash ImagesToText.Client->decode(string $imageFileName, int $timeout)
PHP
array ImagesToText.Client->decode(resource $imageFile, int $timeout)
array ImagesToText.Client->decode(string $imageFileName, int $timeout)
Python
dict imagestotext.Client.decode(file imageFile, int timeout)
dict imagestotext.Client.decode(str imageFileName, int timeout)

GetBalance()

Fetches your current ITT credit balance (in US cents).

.NET
double ImagesToText.Client.GetBalance()
Java
double com.ImagesToText.Client.getBalance()
Perl
float ImagesToText.Client->getBalance()
PHP
float ImagesToText.Client->get_balance()
Python
float imagestotext.Client.get_balance()

CAPTCHA objects/details hashes

.NET and Java clients wrap CAPTCHA details in ImagesToText.Captcha and com.ImagesToText.Captcha objects respectively, exposing CAPTCHA details through the following properties and methods:

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 ITT API clients' usage examples.

C#

    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);
        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 */
    }

Java

    import com.ImagesToText.AccessDeniedException;
    import com.ImagesToText.Captcha;
    import com.ImagesToText.Client;
    import com.ImagesToText.SocketClient;
    import com.ImagesToText.HttpClient;

    /* 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 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 ITT API denied, check your credentials and/or balance */
    }

PHP

    require_once "imagestotext.php";

    /* Put your ITT account username and password here.
       Use ImagesToText_HttpClient for HTTP API. */
    $client = new ImagesToText_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 (ImagesToText_AccessDeniedException) {
        /* Access to ITT API denied, check your credentials and/or balance */
    }

Python

    import imagestotext

    # Put your ITT account username and password here.
    # Use imagestotext.HttpClient for HTTP API.
    client = imagestotext.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 imagestotext.AccessDeniedException:
        # Access to ITT API denied, check your credentials and/or balance

Java and API newrecaptcha, coordinates / image group

    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 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 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);
                    //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(filename, 3, banner, banner_text, "2x4", 0);
                    //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
                } 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);
            }

        }
    }