REST API

Register new developer

The registration is needed for using REST API. Type your email address and you will obtain a password.

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 (). 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 format.

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).
    • 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"
				your_email
				-----------------------------nonRelevantString
				Content-Disposition: form-data; name="password"
				your_password
				-----------------------------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
205DAILY_API_USAGE_LIMIT_EXCEEDED