Face Insights API


The Face Insights API is an HTTP-based RESTful API, using JSON-encoded messages to pass arguments and return responses to:

  • Upload customers images for facial analysis
  • Provide facial insights information:
    • face width measurement
    • face width category
    • face shape categories with assigned distribution per shape
  • Provide facial landmarks (points, lines) to build custom facial analysis theatre

The API uses the HTTPS protocol only and requires Ditto Authentication/Authorization

Full Face Insights API Documentation

Refer to your Developer Reference at face.<your-server-region>.api.ditto.com for specifics on using the Face Insights API.

See below for the generic Developer Reference.

Typical Flow of Face Insights Calls

Sample call flow and responses:

  1. Retrieve ditto_id after completing a Try-On Scan
Face Insights without a Try-On Scan

Face Insights can be implemented independently of the Try-On Scan. In this case, a <ditto_id> will need to be requested ahead of performing any analyses. This can be accomplished via [POST] to the VTO API which returns a <ditto_id>.

  1. Upload frontal image to associated ditto_id:
  • URL [PUT] [host]/faceiq/api/1.0/analyses/<ditto_id>/images/frontal/
  • Request body:
    • Frontal image in the form of binary data
  1. If running face width analysis, upload PD associated with client ditto_id:
  • URL [PUT] [host]/faceiq/api/1.0/analyses/<ditto_id>/client-data/pupillary-distance/
  • Request body:
    • '50.2'
  1. Request all analyses:
  • URL [POST] [host]/faceiq/api/1.0/analyses/<ditto_id>/
  • Request body:
    • JSON list with types of analysis requested
    • Example: ["face-shape", "face-width", "facial-landmarks"]
  • Response
    • { "status": "[host]/faceiq/api/1.0/analyses/<ditto_id>/results/" }
  1. Request all statuses:
  • URL [GET] [host]/faceiq/api/1.0/analyses/<ditto_id>/status/
  • Response:
    • { "facial-landmarks": {"status": "complete"}, "face-shape": {"status": "complete"}, "face-width": {"status": "complete"} }
  1. Request results:
  • URL [GET] [host]/faceiq/api/1.0/analyses/<ditto_id>/results/
  • Response:
    • { "facial-landmarks":{"points": <array-of-points>, "lines": <arrays-of-array-points>}, "face-shape": {"HEART": 47, "SQUARE": 0, "ROUND": 0, "TRIANGLE": 0, "OVAL": 53}, "face-width": {"category": "NARROW", "value": 115.84615384615385} }