API for Masks
This page contains a description of how to get masks via the API for the Face Skin Metrics 3.0
This guide explains how to retrieve and render detection masks produced by the Face Metrics 3.0 application. You’ll learn where masks live in the Results API, which image to pair each mask with, and practical front‑end patterns for SVG and PNG overlays.
How to receive masks from API
Use this endpoint from API doc: API for Images.
You will receive this response:
Key points
Top level:
face_skin_metrics_3indicates the application payload.Per‑parameter: each parameter (e.g.,
pimples,pores,lines,redness) may include amasksobject.By view: masks are grouped by selfie side —
front,left,right.By base image: for each view, masks are provided for specific base images. Common keys:
original— overlay for the raw uploaded face cropaligned_face— overlay for the normalized/aligned face imageanonymised— overlay for the anonymized face image
If a given side or base image is not applicable, its value can be
null.
Example
For example, let's look at the Pimple parameter.
{
"metrics": {
"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
}
}
}
}As in most of the parameters objects, Pimple parameter has the masks key:
{
"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"
}
}
}This key contains an object where the key is selfie side and the value is an object of masks (visualizations of this parameter). Each record in this object has a mask that is applicable to the specific predicted_image .
For example you are showing aligned_face image to users, then to show masks for pimples you need to take the url by this path:
const mask_url = response?.face_skin_metrics_3?.parameters?.pimples?.masks?.front?.aligned_face;How to visualize masks
How to embed SVG mask or image to HTML
Without JavaScript
Using object tag, just insert the generated signed URL into data attribute.
✅ Pros: Retains SVG scalability and interactions.
❌ Cons: Limited browser support and no direct CSS styling.
<object
type="image/svg+xml"
data="https://storage.googleapis.com/...">
</object>With JavaScript
Download SVG content from the signed URL and inject it into your div container.
✅ Pros: Allows direct manipulation via CSS and JS.
❌ Cons: Requires JavaScript to fetch and insert the SVG.
<div id="svg-container"></div>
<script>
fetch("https://storage.googleapis.com/...")
.then(response => response.text())
.then(data => {
document.getElementById("svg-container").innerHTML = data;
});
</script>CSS mask customization example
For example I have the SVG mask for lines:
Let's add colors to the masks. In order to do that, you need to add a CSS rule:
polygon.vectorEffectClass.polygon-lines {
fill: green;
}And the result will be:
You can set any CSS valid rules for SVG HTML tag:
How to visualize PNG masks
Currently we have only 1 PNG mask: for redness parameter.
It looks like this:
In order to show this mask in UI, you need to declare a div block with 2 img tags (styles are important):
<div style="position: relative; display: inline-block;">
<!-- this is the aligned_face image -->
<img style="display: block;" src="https://storage.googleapis.com/cdfdf3a8-7df1-4e31-be7b-3f6a09df5b77/subjects/44aa9f55-e290-4117-81ac-acdeca40bd07/batches/527eca7e-1096-4695-b8fd-af0fc93fd36c/images/a6d2a382-4ad0-4dd6-b0de-ed36f48801a9/face/aligned_face?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=saas-core%40sasuke-core-prd.iam.gserviceaccount.com%2F20250825%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250825T120709Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=host&X-Goog-Signature=35a22d35697f67c0b7d4e3d784a7e9d2e2d5faa30e74f4dc9159a27522b6627e43c8095b9a3faa5f9ba2167c30df969c908d09a85907f3b899020b1dddaf5c900492afc67cc10510c1a70a97791ac9998b2da69b35cf74ad2e36fb356d7f233a510192847e5e1f343b7e241632034d8d9c571aae48ff0d330c5d091448ca23b9762c656ad96caa755267f616dcbf91825ea1f2cecf3905825fbd2521ffb6e5a92833b37193c638f26785c9e7cee1928fd34de70f2d91fdf73cf7f5a70521ba46059bc4a7b25e0910e30170fb5f916bc32abb5de8d191120e2ee3c5adabe117bbfe958f6a9719636183a8e5862b30d299b393b0f892387956123941faa396fc31"></img>
<!-- this is the image of the mask -->
<img style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;" src="https://storage.googleapis.com/cdfdf3a8-7df1-4e31-be7b-3f6a09df5b77/subjects/44aa9f55-e290-4117-81ac-acdeca40bd07/batches/527eca7e-1096-4695-b8fd-af0fc93fd36c/images/a6d2a382-4ad0-4dd6-b0de-ed36f48801a9/masks/aligned_face_redness.png?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=saas-core%40sasuke-core-prd.iam.gserviceaccount.com%2F20250825%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250825T120709Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=host&X-Goog-Signature=c2f42950c5c0aacb9f1de270e6a02df72b09c87eda6b3528ec4cb3a901dc6a2e8fe9d8e29a0d0cb0a703a21d911364bc6a61ca63d64d78317821c19b42c9e941f690c60cc03fe6d8442d89ffdd47f9099d1ef92b2efbf5c3a4081da1336060e57f69b1cdfd2bcf857d9761f0ffb6b01ff2947715b93314749e6963b99054324beba95f97f8fb452b87e580911f652cb59bc59f531a03ceda71bbd2adfe265ea33ba2f3aa96d5bea413d92e399eee8b4d0e930704927d527e7b1e68942560af3d1a667d24ffca3fb08c9e407155b36eb4f94d6defdb28edc2afc5eb8e52cd9effd515a8e7aff16c5fd7d4176fd836593ca30a75a7f1ffcf37aa11699d8ea7dca6"></img>
</div>And the result will be this:
And here is the full HTML file:
Last updated
Was this helpful?