Migrate from Face Skin Metrics 2.0 to Face Skin Analysis 3.0

Face Skin Analysis 3.0 introduces structural changes, updated metric definitions, and new capabilities compared to version 2.0. This guide outlines what’s new, what has changed, and how to migrate.

  1. How to upload

  2. How to send to computation

  3. How to get aux images

  4. How to get results

  5. How to get and show masks

  6. How to map old results

How to upload

Request signed upload URL

Old method

POST /api/v1/companies/{company_id}/subjects/{subject_id}/signed_upload_url/

New method

POST /api/v3/companies/{company_id}/subjects/{subject_id}/upload/

Then as previously you need to make an actual upload request to signed upload URL.

How to send to computation

Old method

POST /api/v1/companies/{company_id}/batches/{batch_id}/compute/

New method

POST /api/v3/companies/{company_id}/batches/{image_batch_id}/compute/

How to get aux images

Old method

GET /api/v1/companies/{company_id}/images/{image_id}/aux_images/

New method

GET /api/v3/companies/{company_id}/batches/{image_batch_id}/results/

Example

{
"face_skin_metrics_3": {
    "image_batch_id": "227c206b-e0ff-425e-9f9d-9716e28ee1de",
    "subject_id": "eca81ec1-4be3-4c06-bd15-61302fa406f8",
    "parameters": {...},
    "survey_results": [],
    "all_algorithms_calculated": true,
    "sc_app_id": null,
    "can_watch_predicted_images": true,
    "predicted_images": {
        "front": {
            "original": "https://storage.googleapis.com/545fd0fb-285a-42f4-8f42-33f818924a5e/subjects/eca81ec1-4be3-4c06-bd15-61302fa406f8/batches/227c206b-e0ff-425e-9f9d-9716e28ee1de/images/6ec4d73d-288b-4221-8051-94f16cff2dd1/face/original?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=saas-core%40sasuke-core-dev.iam.gserviceaccount.com%2F20250603%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250603T164218Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=host&X-Goog-Signature=d73c010c2ead31b4a795eb2b9c3643f93fb1f7253f2f3125c9b8d04d353b3f6b582f1531e1b718f14a60949deaf29806e73ed2c36a6edd884af9284ba1068efe2dc115f0420b2543ed9a6f1a22942f6deca720746d0b91635288b2a970654154e4b5127cbb7458ee2a7e2a1daea055583e47a7e5402b5563f5e8d79e62786e76f582329f48971bec74ddb1b35d60256dfd69813fb265a8e5925ccf9722280fb7de11f0521d71897b287f01dd3a4001066a05b708616f13fb7b8c3b149ffa22d52da33310ef088ac8443c273dd8ef7c8cbb96ac024d3ff867ca4ee20de811bf11061642e289e51bbbd9f14a09a1b2f1b0a5d1ac64dbb4ba9ea5afc6580307de0c",
            "anonymised": "https://storage.googleapis.com/545fd0fb-285a-42f4-8f42-33f818924a5e/subjects/eca81ec1-4be3-4c06-bd15-61302fa406f8/batches/227c206b-e0ff-425e-9f9d-9716e28ee1de/images/6ec4d73d-288b-4221-8051-94f16cff2dd1/face/anonymised?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=saas-core%40sasuke-core-dev.iam.gserviceaccount.com%2F20250603%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250603T164218Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=host&X-Goog-Signature=1be41a3448e8be156a1194997453fddc1cd4b18d670ca51ae9f22c7ba8127b9bf6389599a58d395b576f8148ed16a31a3541701451707874fdea234aaf587f3935666ea1643820a3bf463540678d1cc5b2c8acf3622898ae3cbff73c168db90099e225ae186efd04c959048f165d6c8f1303ece3a0fdaf685c50fb4d747f966ea13cd87017a8d7e9ff5a60f64ff0f2b4b45b1babf87397c1e0cbe8da741a549db711d580423f9a7a2b805b02c52d99ac977a85805461848197cc02d0783c4162a304689533f4e9d6ef6da8caf481f4e65ccff46fb90621ec27a299d1983c90f464933350b5f699d95f66a52875437cb5651fd3a401b26e54544b060bf9c0df5f",
            "aligned_face": "https://storage.googleapis.com/545fd0fb-285a-42f4-8f42-33f818924a5e/subjects/eca81ec1-4be3-4c06-bd15-61302fa406f8/batches/227c206b-e0ff-425e-9f9d-9716e28ee1de/images/6ec4d73d-288b-4221-8051-94f16cff2dd1/face/aligned_face?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=saas-core%40sasuke-core-dev.iam.gserviceaccount.com%2F20250603%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250603T164218Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=host&X-Goog-Signature=5153282eec6e825030bc3ed59ead42dccc43cf03a7e440f3f2319f2dd4750f4efd4222466ee92f9822925fbdcdd91c9d21b10c86bd6a95ed6f89312bf6c5b3733e526b52c8e645cbe6916d03f41f9b4d622ae887edff8ab178ef083c7f1e83a8c6ea7d2143fd35e64472ea0176efaec9f35bb8a08fc779c136b1dc2b376b3cf91e8da518cc054571edc4d5b794a92194f86c93b7b99862813efda90dbf8f067263fd570e0e85583c3a6563e8f5b5aa3e6cccdb4c3998e2ce2a3f22d2449e849ea442d68dde8f06882766a1aa678ab4833487c49ed8baf5f95052100e52571362baf6e3c8014f4f3b2fd8e83a1ed96e52d37a235e402aec4c2302237bdbfae1f8"
        },
        "left": {
            "original": null,
            "anonymised": null,
            "aligned_face": null
        },
        "right": {
            "original": null,
            "anonymised": null,
            "aligned_face": null
        }
    }
    },
"recommendation_system_for_fsm_3": null
}

To get aligned_face image (previously named as restored_selfie_rgba):

aligned_face_url = response.parameters.predicted_images.front.aligned_face # equals "https://storage.googleapis.com/545fd0fb-285a...

This will be a signed URL leading to an image with aligned face based on the original uploaded selfie.

How to get results

Old method

GET /api/v1/companies/{company_id}/images/{image_id}/metrics_and_submetrics/

New method

GET /api/v3/companies/{company_id}/batches/{image_batch_id}/results/

Now all results are calculated per batch basis, not per image, so forget about images.

The result is now an object instead of array, where the key is the parameter name.

Example

{
"face_skin_metrics_3": {
    "image_batch_id": "227c206b-e0ff-425e-9f9d-9716e28ee1de",
    "subject_id": "eca81ec1-4be3-4c06-bd15-61302fa406f8",
    "parameters": {
        "pimples": {
            "areas": {
                "nose": {
                    "amount": 1
                },
                "forehead": {
                    "amount": 3
                },
                "left_eye": {
                    "amount": 0
                },
                "perioral": {
                    "amount": 0
                },
                "right_eye": {
                    "amount": 0
                },
                "left_cheek": {
                    "amount": 0
                },
                "right_cheek": {
                    "amount": 0
                }
            },
            "masks": {
                "front": {
                    "original": "https://storage.googleapis.com/545fd0fb-285a-42f4-8f42-33f818924a5e/subjects/eca81ec1-4be3-4c06-bd15-61302fa406f8/batches/227c206b-e0ff-425e-9f9d-9716e28ee1de/images/6ec4d73d-288b-4221-8051-94f16cff2dd1/masks/original_pimples.svg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=saas-core%40sasuke-core-dev.iam.gserviceaccount.com%2F20250603%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250603T164217Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=host&X-Goog-Signature=12f0f29f0fbac023a5d6ef003c3c6351cdd51c1ab3a16a2a7bf5a8691f4b2a00fc7f2a195fece8d3c73f1d2b122cab42634e6b802237d819754b399ceb37e466205f2fc4d917e9e4eb23bfc6b38469a6995baaedb9842b1b3e68f0d311fac6160832875fb3546d90d6f8298f52a3e23689409661430ee22049f89ab51c0dfcc7594772c26df632f53d00427a49ef6efe0a3482bed876a26b8de845f899da1daf2fa364997751c95bb7c8fcbab735557a17397e6ee55a4838879f60d611f7142bf852d047d58149736cf849fed5ca92b3bbb8afe9a5f0c5da5cffb0a9e7f98e979b104bda5e26c1492db74dedd8576552c067f985810092c28114126c9891c04e",
                    "aligned_face": "https://storage.googleapis.com/545fd0fb-285a-42f4-8f42-33f818924a5e/subjects/eca81ec1-4be3-4c06-bd15-61302fa406f8/batches/227c206b-e0ff-425e-9f9d-9716e28ee1de/images/6ec4d73d-288b-4221-8051-94f16cff2dd1/masks/aligned_face_pimples.svg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=saas-core%40sasuke-core-dev.iam.gserviceaccount.com%2F20250603%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250603T164217Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=host&X-Goog-Signature=341908f6a0312fbd46579343fb54dfd3230869c75233aae3d1e34f746fbc325ef35b79546bf42915b9107bf90c67ee7ff635153dbed745c79b9b3cacb10f335246d2691946323969ca359888ce23c1862ca676b965678974a11211e10f4c7667d459e252daee817c4960977ab181c9c0098cba943fc88ebb475f8a10b2924be01ff27d0c615f00db3921d39ea7ee2f7e5806f4f5482fea2b3bc78a0b819c6b12a9cb96064b3b8e7ac8db83f0bb77fea6dc386c2df3474cd34a5afbec3af92919b4f38d1bb9cb3e5b3bc09ee9777b42d78fd4f13985319a233c5760da4d66105449a862b4c99346009841b3890883059aeeab9e4cdf5329fa102aa0235fb49969",
                    "anonymised": "https://storage.googleapis.com/545fd0fb-285a-42f4-8f42-33f818924a5e/subjects/eca81ec1-4be3-4c06-bd15-61302fa406f8/batches/227c206b-e0ff-425e-9f9d-9716e28ee1de/images/6ec4d73d-288b-4221-8051-94f16cff2dd1/masks/aligned_face_pimples.svg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=saas-core%40sasuke-core-dev.iam.gserviceaccount.com%2F20250603%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250603T164217Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=host&X-Goog-Signature=341908f6a0312fbd46579343fb54dfd3230869c75233aae3d1e34f746fbc325ef35b79546bf42915b9107bf90c67ee7ff635153dbed745c79b9b3cacb10f335246d2691946323969ca359888ce23c1862ca676b965678974a11211e10f4c7667d459e252daee817c4960977ab181c9c0098cba943fc88ebb475f8a10b2924be01ff27d0c615f00db3921d39ea7ee2f7e5806f4f5482fea2b3bc78a0b819c6b12a9cb96064b3b8e7ac8db83f0bb77fea6dc386c2df3474cd34a5afbec3af92919b4f38d1bb9cb3e5b3bc09ee9777b42d78fd4f13985319a233c5760da4d66105449a862b4c99346009841b3890883059aeeab9e4cdf5329fa102aa0235fb49969"
                }
            },
            "amount": 4,
            "algorithm": {
                "name": "pimples",
                "version": 1
            },
            "detection_errors": {
                "left": null,
                "front": null,
                "right": null
            }
        }
    }
    },
"recommendation_system_for_fsm_3": null
}

To access the count of detected pimples for a batch of uploaded images:

pimples_amount = response.parameters.pimples.amount  # equals 4 pimples

How to get and show masks

Old method

GET /api/v1/companies/{company_id}/images/{image_id}/metrics_and_submetrics/

New method

GET /api/v3/companies/{company_id}/batches/{image_batch_id}/results/

Example

{
"face_skin_metrics_3": {
    "image_batch_id": "227c206b-e0ff-425e-9f9d-9716e28ee1de",
    "subject_id": "eca81ec1-4be3-4c06-bd15-61302fa406f8",
    "parameters": {
        "pimples": {
            "areas": {
                "nose": {
                    "amount": 1
                },
                "forehead": {
                    "amount": 3
                },
                "left_eye": {
                    "amount": 0
                },
                "perioral": {
                    "amount": 0
                },
                "right_eye": {
                    "amount": 0
                },
                "left_cheek": {
                    "amount": 0
                },
                "right_cheek": {
                    "amount": 0
                }
            },
            "masks": {
                "front": {
                    "original": "https://storage.googleapis.com/545fd0fb-285a-42f4-8f42-33f818924a5e/subjects/eca81ec1-4be3-4c06-bd15-61302fa406f8/batches/227c206b-e0ff-425e-9f9d-9716e28ee1de/images/6ec4d73d-288b-4221-8051-94f16cff2dd1/masks/original_pimples.svg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=saas-core%40sasuke-core-dev.iam.gserviceaccount.com%2F20250603%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250603T164217Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=host&X-Goog-Signature=12f0f29f0fbac023a5d6ef003c3c6351cdd51c1ab3a16a2a7bf5a8691f4b2a00fc7f2a195fece8d3c73f1d2b122cab42634e6b802237d819754b399ceb37e466205f2fc4d917e9e4eb23bfc6b38469a6995baaedb9842b1b3e68f0d311fac6160832875fb3546d90d6f8298f52a3e23689409661430ee22049f89ab51c0dfcc7594772c26df632f53d00427a49ef6efe0a3482bed876a26b8de845f899da1daf2fa364997751c95bb7c8fcbab735557a17397e6ee55a4838879f60d611f7142bf852d047d58149736cf849fed5ca92b3bbb8afe9a5f0c5da5cffb0a9e7f98e979b104bda5e26c1492db74dedd8576552c067f985810092c28114126c9891c04e",
                    "aligned_face": "https://storage.googleapis.com/545fd0fb-285a-42f4-8f42-33f818924a5e/subjects/eca81ec1-4be3-4c06-bd15-61302fa406f8/batches/227c206b-e0ff-425e-9f9d-9716e28ee1de/images/6ec4d73d-288b-4221-8051-94f16cff2dd1/masks/aligned_face_pimples.svg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=saas-core%40sasuke-core-dev.iam.gserviceaccount.com%2F20250603%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250603T164217Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=host&X-Goog-Signature=341908f6a0312fbd46579343fb54dfd3230869c75233aae3d1e34f746fbc325ef35b79546bf42915b9107bf90c67ee7ff635153dbed745c79b9b3cacb10f335246d2691946323969ca359888ce23c1862ca676b965678974a11211e10f4c7667d459e252daee817c4960977ab181c9c0098cba943fc88ebb475f8a10b2924be01ff27d0c615f00db3921d39ea7ee2f7e5806f4f5482fea2b3bc78a0b819c6b12a9cb96064b3b8e7ac8db83f0bb77fea6dc386c2df3474cd34a5afbec3af92919b4f38d1bb9cb3e5b3bc09ee9777b42d78fd4f13985319a233c5760da4d66105449a862b4c99346009841b3890883059aeeab9e4cdf5329fa102aa0235fb49969",
                    "anonymised": "https://storage.googleapis.com/545fd0fb-285a-42f4-8f42-33f818924a5e/subjects/eca81ec1-4be3-4c06-bd15-61302fa406f8/batches/227c206b-e0ff-425e-9f9d-9716e28ee1de/images/6ec4d73d-288b-4221-8051-94f16cff2dd1/masks/aligned_face_pimples.svg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=saas-core%40sasuke-core-dev.iam.gserviceaccount.com%2F20250603%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250603T164217Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=host&X-Goog-Signature=341908f6a0312fbd46579343fb54dfd3230869c75233aae3d1e34f746fbc325ef35b79546bf42915b9107bf90c67ee7ff635153dbed745c79b9b3cacb10f335246d2691946323969ca359888ce23c1862ca676b965678974a11211e10f4c7667d459e252daee817c4960977ab181c9c0098cba943fc88ebb475f8a10b2924be01ff27d0c615f00db3921d39ea7ee2f7e5806f4f5482fea2b3bc78a0b819c6b12a9cb96064b3b8e7ac8db83f0bb77fea6dc386c2df3474cd34a5afbec3af92919b4f38d1bb9cb3e5b3bc09ee9777b42d78fd4f13985319a233c5760da4d66105449a862b4c99346009841b3890883059aeeab9e4cdf5329fa102aa0235fb49969"
                }
            },
            "amount": 4,
            "algorithm": {
                "name": "pimples",
                "version": 1
            },
            "detection_errors": {
                "left": null,
                "front": null,
                "right": null
            }
        }
    },
"recommendation_system_for_fsm_3": null
}

To access the coordinates of pimples detected in the uploaded batch:

pimples_masks = response.parameters.pimples.masks

The response.parameters.pimples.masks object contains directional mask data for each image in the batch. It may include up to three keys: front, left, and right, depending on the views uploaded.

Each key holds URLs to pre-rendered SVG masks. Here is the example for the front mask:

front_aligned_face_pimples_mask = response.parameters.pimples.masks.front.aligned_face  # equals to signed URL "https://storage.googleapis.com/545fd0fb-285a-42f4-8f42-33f818924a5e/subjects/eca81ec1-4be3-4c06-b...

The signed URL mask will contain an SVG element showing the mask.

Example mask:

Pimples mask svg screenshot
How does the html svg element with masks look like

When you receive a signed URL pointing to an SVG mask (e.g. aligned_face), you can overlay it directly on top of the aligned face image in your UI using standard HTML.

Example how to show SVG in your HTML using JavaScript:

<div id="svg-container"></div>

<script>
fetch("https://storage.googleapis.com/...")
  .then(response => response.text())
  .then(data => {
    document.getElementById("svg-container").innerHTML = data;
  });
</script>

How to map old results

Acne Result Scheme

selfie_v2.acne.result.area_results[0].main_metric.value

Breakouts Parameter Result Scheme

parameters.breakouts.score

Eye Area Condition Result Scheme

selfie_v2.eye_bags.result.area_results[0].main_metric.value

Dark Circles Parameter Result Scheme

parameters.dark_circles.score

Hydration Result Scheme

selfie_v2.hydration.result.area_results[0].main_metric.value

Deprecated in the Face Skin Analysis 3.0

_

Lines Result Scheme

selfie_v2.lines.result.area_results[0].main_metric.value

Lines Result Scheme

parameters.lines.score

Pigmentation Result Scheme

selfie_v2.pigmentation.result.area_results[0].main_metric.value

Pigmentation Parameter Result Scheme

parameters.pigmentation.score

Pores Result Scheme

selfie_v2.pores.result.area_results[0].main_metric.value

Pores Parameter Result Scheme

parameters.pores.score

Redness Result Scheme

selfie_v2.redness.result.area_results[0].main_metric.value

Redness Parameter Result Scheme

parameters.redness.score

Translucency Result Scheme

selfie_v2.translucency.result.area_results[0].main_metric.value

Deprecated in the Face Skin Analysis 3.0

_

Uniformness Result Scheme

selfie_v2.uniformness.result.area_results[0].main_metric.value

Deprecated in the Face Skin Analysis 3.0

–

Skin type Result Scheme

selfie_v2.skin_type.result.area_results[0].main_metric.value

Skin Type Parameter Result Scheme

parameters.skin_type.classification

Skin tone Result Scheme

selfie_v2.skin_tone.result.area_results[0].main_metric.value

Skin Tone Parameter Result Scheme

parameters.skintone.classification

Perceived Age Result Scheme

selfie_v2.age.result.area_results[0].main_metric.value

Perceived Age Parameter Result Scheme

parameters.age.age

ITA (Individual Typology Angle) Result Scheme

selfie_v2.ita.result.area_results[0].main_metric.value

ITA Parameter Result Scheme

parameters.ita.ita

Eye Age Result Scheme

selfie_v2.eyes_age.result.area_results[0].main_metric.value

Eyes Age Parameter Result Scheme

parameters.eyes_age.eyes_age

New & Deprecated Metrics/Parameters

New metrics/parameters

Missing metrics/parameters

PreviousAPI for MasksNextBreakouts Parameter Result Scheme

Last updated

Was this helpful?