Mashape API Documentation

API Walkthrough

To create a 3D reconstruction the following steps are needed:

  1. You upload a user photo to our service (Upload Image), ideally with landmark annotation
  2. Our cloud computes the resulting 3D mesh and texture, which takes approximately 1 minute
  3. You obtain the job status (Get Obj Reconstruction) and download the obj and texture as a Zip file from the provided URL


Upload Image Function

The Upload Image HTTP POST call takes up to 3 parameters:

file (required)

An image file (jpeg/png/gif, no bigger than 2MB in size) with a persons face. Please make sure that the photo adheres to our photo guidelines:

Good Example: Passport Style Photo



Bad Examples:



Occluded Face

  • take hair out of face
  • remove glasses


Facial Expressions

  • don't smile
  • no grimace


Shadows

  • turn on all the lights in your room
  • set your camera to force flash


Pose

  • pose straight and look forward


landmarks (optional)

an optional json object denoting landmark ids and coordinates within the image file. The json format and landmark specifications are below.
If no landmarks are provided we will attempt to detect facial features (with the help of faceplusplus.com), we cannot guarantee that this process succeeds or is accurate enough for a good 3D reconstruction in every case. If you need a robust result in any case we suggest you let your users annotate the necessary landmarks.

landmark json format

landmarks: an object property containing a json array of landmark-points
landmark point: an object denoting one landmark, with properties:
'id': the name of the landmark
'x': the x-coordinate of the landmark in the image in pixels on an left to right axis
'y': the y-coordinate of the landmark in the image in pixels on a top to bottom axis
				
				{
   "landmarks":[
      {
         "id":"landmark1_name",
         "x": 200,
         "y": 300
      },
      {
         "id":"landmark2_name",
         "x":300,
         "y":692
      },
      {
         "id":"'example: top-left corner of image'",
         "x":0,
         "y":0
      },
      {
         "id":"'example: bottom-right corner of image'",
         "x":'image_width-1',
         "y":'image_height-1'
      },
      [ ... ]
   ]
}
				

Landmark IDs

At least 7 landmarks need to be defined, the more landmarks are set, the better the outcome of the reconstruction.
The following landmarks have been defined:
Note: left and right is defined from the viewpoint of the face on the image (the medical way such points are defined), so from a image observer viewpoint left and right are usually interchanged
  • nose_tip # tip of the nose
  • nose_rc # nose right corner
  • nose_lc #nose left corner
  • reye_ic # right eye, inner corner
  • leye_ic # left eye, inner corner
  • reye_oc # right eye, outer corner
  • leye_oc # left eye, outer corner
  • reye_c # right eye, center
  • leye_c # left eye, center
  • mouth_ulb # mouth, upper lip border
  • mouth_llb # mouth, lower lip border
  • mouth_rc # mouth right corner
  • mouth_lc # mouth left corner
  • rear_ic # right ear, inner corner, where the lobe meets the face
  • lear_ic # left ear, inner corner, where the lobe meets the face
  • rebr_ic # right eyebrow, inner corner
  • lebr_ic # left eyebrow, inner corner
  • rebr_oc # right eyebrow, outer corner
  • lebr_oc # left eyebrow, outer corner
  • chin # middle point of the chin line
  • contour_l # a contour point on the left side of the chin line, to be set only once per request
  • contour_r # a contour point on the right side of the chin line, to be set only once per request
  • mouth_ui # mouth upper inner corner of the lip (if the mouse is closed this is the mouth centerpoint)
  • mouth_li # mouth lower inner corner of the lip

We suggest to have an interface that requests at least the eight landmarks above in bold.

gender (optional)

an optional string denoting the gender of the person: either "male" or "female"

Upload Image Successful Response (HTTP 200)

{
  "state": "success",
  "fitid": "fit:59CAA390-0633-4CBB-BA69-FA788D2C62DE",
  "user": "vizago"
}
  • state: string, either "success" or "error"
  • fitid: string, a unique id that denotes the reconstruction to be created
  • user: string, your mashape user id

Error Responses (HTTP 4xx or 5xx)

{
   "error":{
      "id":27,
      "message":"fitid not found"
   },
   "state":"error"
}
				
  • error: an object denoting an error
    • id: integer, the errorid
    • message: string, a human readable error message
  • state: string, denotes the error with "error"

Get Obj Function

GetObj is called with the respective fitid, returned from the UploadImage call. It returns information about the job status of the 3D reconstruction and once it completes, the download url of the obj zip file.

GetObj only takes one parameter: fitid as a HTTP GET parameter:

fitid (required)

A string identifier of the fit, whose information you would like to obtain.

GetObj Successful Response
(HTTP 200)

Response while job is executing:

					
{
  "uuid": "fit:3B64D4A6-7C9A-4F81-8751-8438BD3398AB",
  "job": "pending",
  "jobtime": "2014-03-08_08-13-41",
  "user": "vizago",
  "state": "success"
}					

  • state: string, either "success" or "error", denotes the state of your call and not whether the job has yet completed.
  • uuid: string, a unique id that denotes the reconstruction
  • user: string, your mashape user id
  • job: string, denotes the state of the job, "pending" or "done"
  • jobtime: string denoting the starting time of the job

Response once job has completed:

					
{						
  "faceurl": "https://domain.com/fit_id.zip",
  "uuid": "fit:8A8B8048-9297-4D70-91BB-5134CFA5D9CC",
  "user": "vizago",
  "job": "done",
  "jobtime": "2014-02-28_15-30-06",
  "imagerecommendations": [
    "redo",
    "shadows"
  ],
  "state": "success"
}						

  • state: string, either "success" or "error", denotes the state of your call and not whether the job has yet completed.
  • uuid: string, a unique id that denotes the reconstruction
  • user: string, your mashape user id
  • job: string, denotes the state of the job, "pending" or "done"
  • jobtime: string denoting the starting time of the job
  • faceurl: string, containg a signed url to download a zip file containg the obj data
    The signed url is valid for 24 hours starting from the jobtime
  • imagerecommendations (OPTIONAL): a list of strings containing tokes of recommended improvements, given the image. The presence of this property indicates that the image does not fully comply with our recommendations and the reconstruction quality may be non-optimal. The following tokens are defined:
    • toobright: “Your image is very bright, consider making one that is just a tad less bright.”
    • toodark: “Your image is very dark, try taking one outside or facing a window during the day.”
    • shadows: “Your face is uneven lit, please try facing your brightest light source frontally (i.e. face a window during the day”
    • redo: “Something was weird with your image. We think we can do better if you give us another chance and you follow the recommendations for taking an image.”
    • nonfrontal: “Your face pose is not optimal, try to face the camera frontally”
    • hair: “You might have hair over your face, make sure your hair is not occluding your fronthead and face. Use a hair ribbon if it helps.”
    • lowres: “Your image has a very low resolution. Have a friend snap a picture with the rear facing camera to get better previews.”
    • noise: "Your image is noisy/grainy, consider a better lit environment or lower iso settings while taking the image.

Error Responses (HTTP 4xx or 5xx)

{
   "error":{
      "id":27,
      "message":"fitid not found"
   },
   "state":"error"
}
				
  • error: an object denoting an error
    • id: integer, the errorid
    • message: string, a human readable error message
  • state: string, denotes the error with "error"

Zip file contents

The zip file you obtain from downloading the file at the "faceurl" location has the following structure:

  • /inputImage.obj (wikipedia)
  • /inputImage.mtl The corresponding materials file
  • /inputImage_tex.jpeg The corresponding texture file
Please note that the obj references the mtl file and the mtl file references the texture file, so you cannot simply change the file names