elxsy where humanity wins the fight against machines

API

Please visit Docs and FAQ section about implementations and examples about ImHuman Api

Table of Contents

  1. Introduction
  2. Expected Parameters
  3. Response Format
  4. Response Values
  5. Error Codes

Introduction

Browsing this page I guess you know what an API is, if you don't in short it is a common language to share data and information in our case. It is language independent, meaning that you can access the information with any web enabled language and method. Usually some big and control freak APIs needs several communication messages in order to service. But fortunately our simple one only needs one comminucation. Here is how it works in short;

  1. Your website is going to display some content that requires human|bot check, so with your identification and parameters it asks the ImHuman API for humanizers*
  2. If identification and parameters are correct ImHuman API provides you with humanizers.

* Humanizer is an 1 by 3 arrray | object which includes the image, name and value for an input

Expected Parameters

For the ease of use ImHuman API requires parameters via GET method.

Simple words, http://www.url.com?param1=1&param2=2

Parameters Table. All parameters are consisted of small case letters

PARAMETER TYPE REQUIRED EXPLANATION
api Double YES Version of Client API-Library. Exists in order to prevent conflicts if a future API update takes place. ImHuman API will reject requests made from clients who are using libraries older than Minimum Client Library version.
user String YES API user value for the identification. Generated by control panel automatically when you add a website.
key String YES API key value for the identification. Automatically generated also
row Integer YES How many rows of humanizers to return.
Creates GRID with the col value where GRID = row * col
GRID can not be bigger than 25
col Integer YES How many columns of humanizers to return
sel Interger YES How many humanizers needs to be selected. Minimum 2 maximum GRID - 1, which is 24

Response Format

ImHuman API reponds in JSON format. PHP decodes the JSON format by default with the json_decode() function from PHP 4.4.x I guess and if not there are tons of libraries made for json parsing for PHP and many languages. Best resource is json.org, which includes all libraries in nearly all languages.

Response Values

VALUE TYPE EXPLANATION
APIV Double Current ImHuman API version which ImHuman API runs on. Just for debugging
MAPIV Double Currently required Minimum Client Library version to connect to API
CLAPIV Double Currently connected client's library version. (debugging)
ERROR Integer Error Identification Number which returns 0 on ne error and starts from 100 on errors
RSP String

If an error occured returns the explanation of the error code
If not, returns the contents of Response

RSP::WORD String The word | tag needs to be selected through humanizers
RSP::ANSWER String Answer for the correct humanizer selection.
RSP::GRID Array|Object Consists or [row * col] by [3] array.
[row * col ][ i ] :: [ src = humanizer source ][ name = humanizer unique name][ value= humanizer unique value ]

Error Codes

ERROR CODE ERROR STRING
100 NO USER SUPPLIED
101 NO KEY SUPPLIED
102 NO ROW SUPPLIED
103 NO COLUMN SUPPLIED
104 NO SELECTION SUPPLIED
105 NO API SUPPLIED
106 PLEASE UPDATE YOUR API TO CURRENT VERSION
107 IMHUMAN API DATABASE CONNECTION ERROR
108 MINIMUM 3 HUMANIZERS REQUIRED
109 MINIMUM 2 SELECTION REQUIRED
110 SELECTION CAN NOT BE BIGGER THAN (OR EQUAL TO) GRID
111 INVALID API USER | KEY
112 MAXIMUM GRID SIZE 25
113 SELECTION IS TOO BIG
114 DB ERROR

 

Comments (12) Trackbacks (0)
  1. How can i get my api for my site?

  2. Visit Control Panel and click on create website link.

  3. and my site ip???

  4. Why do I have empty boxes?
    How to put the picture?
    Help, all set in the instructions.

  5. I want to receive words in Russian. But i receive ?????? in the word field in JSON by the link http://api.elxsy.com/?api=1.0&user=my_user_id&key=my_user_key&row=1&col=5&sel=3&lang=ru. It works great if i use lang=en. But i need Russian. What can i do?

  6. I’m trying to figure this out, but it’s just not coming to me. How in the world do I get an API key?

    I’ve clicked on “Create Website” on the control panel page. But the only thing that happens is the page goes dark (all except the menu on the top bar). What am I doing wrong?

    Btw, this is a great idea.

    Edit: I’m trying to click through to post this comment, but I’m getting some images that say “This image not available”. So, I don’t know if it’s a muffin or not!

    • Update: I’ve registered on this site and have gotten my API ID and key. I’ve also entered those details into my site’s settings.

      However, on my site it’s saying “Please select all: (s):” and there are just five empty boxes.

  7. One of pictures on Flikr unavailable. May I use own pictures from my site, not flikr?

    • Unfortunately not at this moment, but I am reviewing the API and functionality;

      • Remove necessary username-key and have a check for
      • Fully RESTFUL API
      • Public management and moderation
      • Public internalization and customization
      • Flickr image hashchecks to make sure we don’t get the unavailable image

      I think those changes will make a better API and experience :)

  8. Hello! I’ve clicked on “Create Website”, have got password, but at my profile page I can not see API key. Where can I see it?


Leave a comment

No trackbacks yet.