Retrieving Face Shape, Face Width, PD, and Facial Landmarks from the Face Insights API using Postman


Introduction

This guide will walk you through how to perform a Face Insights analysis on a scanId and then retrieve the results (face shape, face width, pupillary distance, and facial landmarks) using Postman.

It is assumed that an end-user successfully performed the side-to-side head turn and Scale Step within the Try-On Scan.


Getting Started

  1. Download and install Postman, if you do not already have it.
  2. Open Postman and create a new request by clicking the “New” button in the top left corner.
  3. Name the request PUT /analyses/{scanId}/images/frontal/ and save it to a collection or folder.
  4. Create another request, POST /analyses/{scanId}/ and save it to a collection or folder.
  5. Create another request, name it GET /analyses/{scanId}/results/{service}/, and save it to a collection or a folder.
  6. Retrieve the scanId upon which you would like to perform a Face Insights analysis.
Pre-reqs for retrieving face width and PD ahead of the FaceIQ analysis

To retrieve face width and PD from card scale via the Face Insights API, Card Scale must have been successfully completed within the Try-On Scan ahead of the analysis.

To retrieve face width from PD scale, PD must have been passed into the faceAnalysisData config option of Ditto.Scan and VTO must have been completed successfully ahead of the analysis.

Alternatively, to retrieve face width from PD scale without performing a Virtual Try-On, one must update the PD associated with a scanId (via Try-On API’s PUT /dittos/{scanId}/ endpoint) and upload a frontal image (via Face Insight API’s PUT /analyses/{scanId}/images/frontal/) ahead of the analysis.


Building and Executing the Requests

In order to retrieve face shape, face width, PD, and facial landmarks, you must first perform a PUT request on the /analyses/{scanId}/images/frontal endpoint. Then a POST request on the /analyses/{scanId} endpoint and then a GET request on the /analyses/{scanId}/results/{service} endpoint.

Skip Step 1. if using FaceInsights via BSDK

Step 1. PUT /analyses/{scanId}/images/frontal

The PUT request on the /analyses/{scanId}/images/frontal endpoint will cause frontal image to be uploaded for the specified scanId.

Endpoint URL:

Substitute the correct values for {-server}, {partner}, and {scanId} below to build the endpoint URL.

https://face{-server}.{partners}.api.ditto.com/faceiq/api/1.0/analyses/{scanId}/images/frontal

Required headers:

  1. X-Ditto-Access-Key-Id
    • Access Key ID provided by Ditto
  2. X-Ditto-Signature
  3. Content-Type: image/jpeg

Request body:

The request body is a binary frontal image which is used for the analysis.

Enter all of the above information into Postman, and then click the blue “Send” button!

Step 2. POST /analyses/{scanId}/

The POST request on the /analyses/{scanId}/ endpoint will cause specified analyses to be performed on the specified scanId.

Endpoint URL:

Substitute the correct values for {-server}, {partner}, and {scanId} below to build the endpoint URL.

https://face{-server}.{partners}.api.ditto.com/faceiq/api/1.0/analyses/{scanId}

Required headers:

  1. X-Ditto-Access-Key-Id
    • Access Key ID provided by Ditto
  2. X-Ditto-Signature
  3. Content-Type: application/json

Request body:

The request body is an array of one or more analyses to perform.

Ex: ["face-shape", "facial-landmarks", "face-width", "pupillary-distance"]

Enter all of the above information into Postman, and then click the blue “Send” button!

Step 3. GET /analyses/{scanId}/results/{service}/

The GET request on the /analyses/{scanId}/results/{service}/ endpoint allows you to retrieve the result of the Face Insights anaylsis for the specified service.

Endpoint URL:

https://face{-server}.{partners}.api.ditto.com/faceiq/api/1.0/analyses/{scanId}/results/{service}

The {service} can be any of the ones specified in the body of the POST request (e.g., face-shape, facial-landmarks, face-width, pupillary-distance).

Required headers:

  1. X-Ditto-Access-Key-Id
    • Access Key ID provided by Ditto
  2. X-Ditto-Signature

Click “Send” and if your request is successful, you will see the result of the FI analysis for the specified service in the response body!


Troubleshooting

  1. If you receive a “401 Unauthorized” error with a response body
    "status": "unauthorized",
    "detail": "invalid authentication credentials"
    

, your Access Key ID or Overlay Signature may be incorrect.

  1. If you receive a “Could not get any response”, then your endpoint URL is incorrect.

    • Ensure that you are hitting a Prod or Sandbox server listed in your 1Password vault.
    • Ensure you’ve entered the correct {scanId}
  2. If you receive a “404 Not Found” with a response body

    "status": "not found",
    "detail": "{} resource not found"
    

    , ensure that you’ve specified a {service} that exists and that you included it in the body of the POST request.


Conclusion

Congratulations! You’ve completed the “Retrieving Face Shape, Face Width, PD, and Facial Landmarks from the Face Insights API using Postman” guide. Building these requests into code should be straightforward from here.

If you have any questions, don’t hesitate to reach out to your CSM or Solutions Engineer!