For the complete documentation index, see llms.txt. This page is also available as Markdown.

Migrate from Face Skin Metrics 2.0 to Face Skin Analysis 3.0

What changed between Face Skin Metrics 2.0 and Face Skin Analysis 3.0, and how to migrate your integration to the new version.

What changes

If you upload with signed URLs, the photo upload itself stays the same: you still request a signed URL, PUT the file to it, and then send the batch to computation. What changes is the endpoint versions, how results are read, and how results are shaped.

If you upload photos as base64 (b64data) to the v1 images endpoint, the analysis starts on upload and there is no compute call. Switch to the signed URL upload and the compute call below.

Face Skin Metrics 2.0 (old)
Face Skin Analysis 3.0 (new)

Application tech_name

face_skin_metrics_2.0

face_skin_metrics_3

Request an upload URL

POST /api/v1/.../subjects/{subject_id}/signed_upload_url/

POST /api/v3/.../subjects/{subject_id}/upload/

Upload the file

PUT to the signed URL

Same. PUT to the signed URL

Base64 upload

b64data in the v1 image upload, which starts the analysis on upload

Not used. Request a signed URL, PUT the file, then call compute

Group of photos

image_batch_id from the upload response, passed as batch_id

Same batch, passed as image_batch_id

Start the analysis

POST /api/v1/.../batches/{batch_id}/compute/

POST /api/v3/.../batches/{image_batch_id}/compute/

Read results

GET /api/v1/.../images/{image_id}/metrics_and_submetrics/, once per image

GET /api/v4/.../batches/{image_batch_id}/results/, once per batch

Result shape

An array of metric objects

One face_skin_analysis_3 object. Each parameter is a key, for example face_skin_analysis_3.parameters.pores

Masks and aux images

GET /api/v1/.../images/{image_id}/aux_images/ and the metrics response

Inside the same results response: parameters that support masks carry them, and predicted_images holds the images

Results history for a subject

GET /api/v1/.../subjects/{subject_id}/metrics_and_submetrics/

GET /api/v4/.../subjects/{subject_id}/results/

Photo quality

Image quality algorithm inside the 2.0 result

parameters.quality (front, left, right)

Webhook payload

Webhook v1 payload with the 2.0 metrics

The Webhook v1 batch payload also carries the 3.0 results, under face_skin_metrics_3. The per-photo v1 payload does not. Webhook v3 is recommended

Migration steps

Attach Face Skin Analysis 3.0 to your dataset

Results only appear for applications attached to the dataset you upload to. Attach Face Skin Analysis 3.0 before you switch your upload code:

See API for Algorithm Applications for the request details and dependency handling. Attaching Face Skin Analysis 3.0 does not remove Face Skin Metrics 2.0 from the dataset, so both can run on new batches while you migrate. Photos analysed before you attach it keep their old results only.

Face Skin Analysis 3.0 returns 15 Basic parameters for every company. The 34 Advanced parameters need the Advanced metrics add-on, which your account manager enables. See How to map old results.

How to upload

Request signed upload URL

Old method

New method

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

How to send to computation

Old method

New method

How to get aux images

Old method

New method

Example

To get aligned_face image (previously named as restored_selfie_rgba):

This is a signed URL leading to an image with aligned face based on the original uploaded selfie. If can_watch_predicted_images is false for the user who makes the request, predicted_images comes back with front, left, and right set to null.

How to get results

Old method

New method

Example

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

How to get and show masks

Old method

New method

Example

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

The response.face_skin_analysis_3.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:

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:

How to know when results are ready

Results are calculated per batch, and Face Skin Analysis 3.0 can return them before every parameter is done. Always check face_skin_analysis_3.all_algorithms_calculated before you treat the result as complete.

Configure a Webhook v3 on your dataset. The platform sends a POST to your server when a batch is processed. The webhook's version setting picks the payload shape, and new webhooks use v4 unless you set v3:

  • v4: the batch is batch_id, an images object lists the uploaded photos, and the results are under face_skin_metrics_3.

  • v3: the batch is image_batch_id, and the results are under face_skin_metrics_3.

In both shapes, face_skin_metrics_3 carries the same all_algorithms_calculated flag and parameters. Use the batch ID to fetch the full result with GET /api/v4/.../batches/{image_batch_id}/results/ if you need masks or predicted images.

Already use a Webhook v1? Its batch payload also carries the 3.0 results, under face_skin_metrics_3, so you can keep it. The per-photo v1 payload carries only the 2.0 metrics, so move per-photo webhooks to Webhook v3. Either way, update your handler to read the 3.0 results instead of the 2.0 metrics, and update anything downstream that reads them (CRM, analytics). See Webhooks v3 for the payload, the secret_key check, and retries.

Polling

No endpoint reports on its own whether results are ready. GET /api/v3/companies/{company_id}/batches/{image_batch_id}/ returns the batch itself, not the progress of the analysis. To know when results are complete, poll the results endpoint:

While the batch is still processing, the response can contain only the parameters finished so far, with face_skin_analysis_3.all_algorithms_calculated: false. Keep waiting; this is not an error. Stop when the flag is true, or when you give up. Most batches finish in a few seconds, so poll every 1-2 seconds for up to 15-20 seconds, with a delay between calls.

How to map old results

Face Skin Analysis 3.0 returns 49 parameters: 15 Basic parameters that are always calculated, and 34 Advanced parameters. The tables below map every one of them back to its Face Skin Metrics 2.0 counterpart, where one exists.

Face Skin Analysis 3.0 paths are relative to the face_skin_analysis_3 object returned by GET /api/v4/companies/{company_id}/batches/{image_batch_id}/results/. A path such as parameters.pores.score is read as response.face_skin_analysis_3.parameters.pores.score.

Face Skin Metrics 2.0 paths are shown in short form. selfie_v2.pores → main_metric.value means selfie_v2.pores.result.area_results[0].main_metric.value. Some 3.0 parameters map to a sub-metric of a 2.0 algorithm rather than to its main metric — those are shown as selfie_v2.<algorithm> → sub_metrics → <key>.

Basic parameters

Always returned for every batch.

Face Skin Analysis 3.0 parameter
Result path in 3.0
Face Skin Metrics 2.0 equivalent
Result path in 2.0

parameters.age.age

selfie_v2.age → main_metric.value

parameters.breakouts.score (also .grade)

selfie_v2.acne → main_metric.value

parameters.dark_circles.score (also .grade)

selfie_v2.eye_bags → sub_metrics → dark_circles_score

parameters.eyes_age.eyes_age

selfie_v2.eyes_age → main_metric.value

parameters.hydration.score (also .grade)

selfie_v2.hydration → main_metric.value

parameters.lines.score (also .grade)

selfie_v2.lines → main_metric.value

parameters.pigmentation.score (also .grade)

selfie_v2.pigmentation → main_metric.value

parameters.pores.score (also .grade, .amount)

selfie_v2.pores → main_metric.value

parameters.puffiness.score (also .grade)

selfie_v2.eye_bags → sub_metrics → eye_bags_score

parameters.quality.front / .left / .right

selfie_v2.quality → main_metric.value

parameters.redness.score (also .grade)

selfie_v2.redness → main_metric.value

parameters.sagging.score (also .grade)

selfie_v2.lines → sub_metrics → sagging_score

parameters.skin_type.classification

selfie_v2.skin_type → main_metric.value

parameters.skintone.classification

selfie_v2.skintone-classification → main_metric.value

parameters.uniformness.score (also .grade)

selfie_v2.uniformness → main_metric.value

selfie_v2.skin_type and selfie_v2.sagging were unpublished or disabled by default in Face Skin Metrics 2.0, so many integrations never received them. In Face Skin Analysis 3.0 both are Basic parameters and are always returned.

Advanced parameters

Face Skin Analysis 3.0 parameter
Result path in 3.0
Face Skin Metrics 2.0 equivalent
Result path in 2.0

parameters.ita.ita (also .classification, .l_channel, .a_channel, .b_channel)

selfie_v2.skin_tone → sub_metrics → ita_score

parameters.fine_lines.score (also .grade)

selfie_v2.wrinkles → sub_metrics → fine_wrinkles_density

parameters.deep_lines.score (also .grade)

selfie_v2.wrinkles → sub_metrics → deep_wrinkles_density

parameters.nasolabial_wrinkles.grade

—

—

parameters.marionette_lines.grade

—

—

parameters.forehead_lines.grade (also .amount, .length)

—

—

forehead_fine_lines

parameters.forehead_fine_lines.amount (also .length)

—

—

forehead_deep_lines

parameters.forehead_deep_lines.amount (also .length)

—

—

parameters.glabellar_lines.grade (also .amount, .length)

—

—

glabellar_fine_lines

parameters.glabellar_fine_lines.amount (also .length)

—

—

glabellar_deep_lines

parameters.glabellar_deep_lines.amount (also .length)

—

—

parameters.lip_lines.grade (also .amount, .length)

—

—

lip_fine_lines

parameters.lip_fine_lines.amount (also .length)

—

—

lip_deep_lines

parameters.lip_deep_lines.amount (also .length)

—

—

parameters.under_eye_lines.grade (also .amount)

—

—

under_eye_fine_lines

parameters.under_eye_fine_lines.amount

—

—

under_eye_deep_lines

parameters.under_eye_deep_lines.amount

—

—

parameters.crows_feet_lines.grade (also .amount)

—

—

crows_feet_fine_lines

parameters.crows_feet_fine_lines.amount

—

—

crows_feet_deep_lines

parameters.crows_feet_deep_lines.amount

—

—

parameters.eyes_lines.grade (also .score)

—

—

parameters.jowls.grade

selfie_v2.lines → sub_metrics → jowls_grade

parameters.lacrimal_grooves.score (also .grade)

selfie_v2.eye_bags → sub_metrics → lacrimal_grooves_score

parameters.enlarged_pores.amount

selfie_v2.pores → sub_metrics → pores_number

parameters.freckles.density

—

—

parameters.moles.amount

—

—

parameters.melasma.density

—

—

parameters.sun_spots.density (also .amount, .grade, .score)

selfie_v2.age_spots (feature-flagged in 2.0, no doc page)

selfie_v2.age_spots → main_metric.value

parameters.pimples.amount (also .grade)

—

—

parameters.papules.amount (also .grade)

—

—

parameters.pustules.amount (also .grade)

—

—

parameters.inflammation.density (also .grade)

—

—

parameters.post_acne_hyperpigmentation.density (also .grade)

—

—

parameters.irritation.score (also .grade)

—

—

New & Deprecated Metrics/Parameters

New in Face Skin Analysis 3.0

Parameters with no Face Skin Metrics 2.0 counterpart:

These existed in Face Skin Metrics 2.0 only as sub-metrics of another algorithm. In Face Skin Analysis 3.0 they are parameters in their own right:

Missing in Face Skin Analysis 3.0

How to turn off Face Skin Metrics 2.0

When your integration reads only Face Skin Analysis 3.0 results, detach Face Skin Metrics 2.0 from the dataset. A detached application stops running on new batches that you send with POST /api/v3/.../batches/{image_batch_id}/compute/.

A 200 response means Face Skin Metrics 2.0 is now off for that dataset. Detach works per dataset, so repeat the call for every dataset that has Face Skin Metrics 2.0 attached. To turn it on again, attach it to the dataset again. Send the enabled_algorithms and algorithms_flags you used before: an attach without them resets the application to its default algorithms and no flags.

Before you detach:

  • Detach dependent applications first. These applications need Face Skin Metrics 2.0: Recommendation Engine, Recommendation System for FSM 2.0, and the SkinGPT generated-vs-original comparison applications. The detach request does not check for them, so they would stay attached with no input. Switch Recommendation System for FSM 2.0 to Recommendation System for FSM 3. The other applications have no Face Skin Analysis 3.0 counterpart, so detach them.

  • Switch your code first. Once your upload and compute calls use v3, and your results and webhook code read the 3.0 results, detach. Detaching earlier leaves your integration without results.

  • Old 2.0 results are hidden from v4, not deleted. Turning Face Skin Metrics 2.0 off does not delete its results. But v4 batch and subject results, Webhook v1, and Webhook v3 with version set to v4 show results only for applications that are on. So face_metrics_2 disappears from them, for old batches too. GET /api/v1/.../images/{image_id}/metrics_and_submetrics/ still returns the 2.0 results, and attaching Face Skin Metrics 2.0 again shows them in v4 again.

  • System datasets cannot be edited. The request returns a permission error for them.

  • The dataset must have the application attached. Otherwise you get an application_not_attached error.

Migration checklist


Book a demo external-linkFace Skin Analysis 3.0 on haut.ai

Last updated