REST API Documentation

REST Interafce

API uses REST-like interface. This means that all calls to the API are made over the Internet, using HTTP GET and POST requests to the API server (http://cloud.eyedea.cz/api/v2). Any programming language that can be used to communicate over HTTP can be used for client-side implementations.

Photo can be uploaded directly in the API request. A requests that uploads a photo must be formed as a MIME multi-part message sent using POST data. Each argument, including the raw image data, should be specified as a separate chunk of form data. (See example below)

Responses are returned in JSON.

API Methods

usage notes:

All coordinates are provided in % values to support any photo scale. Photo width and height (vs. frame width/height) are provided in pixels.

The maximum image size you can treat with is 10MB.

url:

http://cloud.eyedea.cz/api/v2/facedetect.json

parameters:
  • email - the email provided by user during registration.
  • password - the user's password obtained after registration.
  • url (use only with GET method) - an URL of inspected image.
  • upload (use only with POST method) - uploaded image file.
return values:
  • photos [array] - a list of photos (in actual version only one photo at time can be passed to the function).
    • url [string] - same as parameter url.
    • width [integer]
    • height [integer]
    • tags [array]
      • width [float] - frame width of detected face.
      • height [float] - frame height of detected face.
      • center [array] - frame center of detected face.
        • x [float]
        • y [float]
      • yaw [float] - yaw of the face in degrees.
      • attributes [array]
        • age_est [array]
          • value [integer]
        • gender [array]
          • value [string] - could be "male","female" or "unknown".
        • emotion [array]
          • value [string] - could be "smiling","not smiling" or "unknown".
      • leftCanthusRightEye [array]
        • x [float]
        • y [float]
      • rightCanthusLeftEye [array]
        • x [float]
        • y [float]
      • mouthRight [array]
        • x [float]
        • y [float]
      • mouthLeft [array]
        • x [float]
        • y [float]
      • rightCanthusRightEye [array]
        • x [float]
        • y [float]
      • leftCanthusLeftEye [array]
        • x [float]
        • y [float]
      • noseTip [array]
        • x [float]
        • y [float]
      • leftEyebrowLeft [array]
        • x [float]
        • y [float]
      • leftEyebrowCenter [array]
        • x [float]
        • y [float]
      • leftEyebrowRight [array]
        • x [float]
        • y [float]
      • rightEyebrowLeft [array]
        • x [float]
        • y [float]
      • rightEyebrowCenter [array]
        • x [float]
        • y [float]
      • rightEyebrowRight [array]
        • x [float]
        • y [float]
      • noseRoot [array]
        • x [float]
        • y [float]
      • noseLeft [array]
        • x [float]
        • y [float]
      • noseRight [array]
        • x [float]
        • y [float]
      • mouthTop [array]
        • x [float]
        • y [float]
      • mouthBottom [array]
        • x [float]
        • y [float]
      • chin [array]
        • x [float]
        • y [float]
  • status [string] - could be "success" or "failure".
  • error_code [integer] - specified only when an error occurs.
  • error_message [string] - specified only when an error occurs.

Note: Red marked values are returned only if yaw is between -30 and 30 degrees.

GET example:

http://cloud.eyedea.cz/api/v2/facedetect.json?email=youremail&password=yourpassword&url=http://cloud.eyedea.cz/api/static/images/face_example01.jpg

POST example: (post to http://cloud.eyedea.cz/api/v2/facedetect.json)

    Content-Type: multipart/form-data; boundary=nonRelevantString
    Content-Length: 104687
    -----------------------------nonRelevantString
    Content-Disposition: form-data; name="email"
    youremail
    -----------------------------nonRelevantString
    Content-Disposition: form-data; name="password"
    yourpassword
    -----------------------------nonRelevantString
    Content-Disposition: form-data; name="upload"; filename="image.jpg"
    Content-Type: image/jpeg
    

Code example in python:

import apiclient

x = apiclient.faceDetect('your_email', 'your_password', 'face_example01.jpg')
    
Download python api client

The apiclient can be also called directly from command line:

python apiclient.py faceDetect -e your_email -p your_password -img face_example01.jpg
    

error codes:
error_codeerror_message
20IMG_DECODE_ERROR
29UPLOAD_ERROR
31DOWNLOAD_ERROR_FILE_NOT_FOUND
33DOWNLOAD_ERROR_FILE_TOO_LARGE
34DOWNLOAD_ERROR_MALFORMED_URL
104INTERNAL_ERROR
204INVALID_LOGIN
402MISSING_ARGUMENTS