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.
Face Skin Metrics 2.0 will be deprecated by the end of 2026. Move your integration to Face Skin Analysis 3.0 before then. This page is the migration guide.
Starting a brand-new integration? You do not need this page. Follow Configure Your App Backend and SaaS for Integration and Integrate Haut.AI Image Analysis with Your App.
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.
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
Results are now calculated and returned per batch, not per image. You read one response for the whole batch. Masks and predicted images inside it are still split by side: front, left, and right.
The result is now an object instead of an array. Parameters are under face_skin_analysis_3.parameters, and each key is a parameter name.
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:


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.
Webhooks (recommended)
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 isbatch_id, animagesobject lists the uploaded photos, and the results are underface_skin_metrics_3.v3: the batch isimage_batch_id, and the results are underface_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.
Basic parameters
Always returned for every batch.
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
Advanced parameters
Advanced parameters are returned only if the Face Skin Analysis Advanced metrics add-on is enabled for your company. Contact your account manager to enable it.
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
forehead_fine_lines
parameters.forehead_fine_lines.amount (also .length)
—
—
forehead_deep_lines
parameters.forehead_deep_lines.amount (also .length)
—
—
glabellar_fine_lines
parameters.glabellar_fine_lines.amount (also .length)
—
—
glabellar_deep_lines
parameters.glabellar_deep_lines.amount (also .length)
—
—
lip_fine_lines
parameters.lip_fine_lines.amount (also .length)
—
—
lip_deep_lines
parameters.lip_deep_lines.amount (also .length)
—
—
under_eye_fine_lines
parameters.under_eye_fine_lines.amount
—
—
under_eye_deep_lines
parameters.under_eye_deep_lines.amount
—
—
crows_feet_fine_lines
parameters.crows_feet_fine_lines.amount
—
—
crows_feet_deep_lines
parameters.crows_feet_deep_lines.amount
—
—
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.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.post_acne_hyperpigmentation.density (also .grade)
—
—
New & Deprecated Metrics/Parameters
New in Face Skin Analysis 3.0
Parameters with no Face Skin Metrics 2.0 counterpart:
Lines by facial region — Forehead Lines Parameter Result Scheme, Glabellar Lines Parameter Result Scheme, Lip Lines Parameter Result Scheme, Under Eye Lines Parameter Result Scheme, Crow's Feet Lines Parameter Result Scheme, Eye Lines Parameter Result Scheme, Nasolabial Wrinkles Parameter Result Scheme, Marionette Lines Parameter Result Scheme, and their
_fine_lines/_deep_linesvariantsPigmentation breakdown — Freckles Parameter Result Scheme, Moles Parameter Result Scheme, Melasma Parameter Result Scheme
Promoted to top-level parameters
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:
Under Eye Puffiness Parameter Result Scheme — was
eye_bags_scoreinsideselfie_v2.eye_bagsSagging Parameter Result Scheme — was
sagging_scoreinsideselfie_v2.linesLacrimal Grooves Parameter Result Scheme — was
lacrimal_grooves_scoreinsideselfie_v2.eye_bagsJowls Parameter Result Scheme — was
jowls_gradeinsideselfie_v2.linesITA Parameter Result Scheme — was
ita_scoreinsideselfie_v2.skin_tone
Missing in Face Skin Analysis 3.0
Translucency Result Scheme — no direct equivalent. The closest signal is Skin Type Parameter Result Scheme.
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/.
Move to v3 compute before you detach. The v1 compute call, POST /api/v1/.../batches/{batch_id}/compute/, still runs detached applications. Batches you send that way keep getting Face Skin Metrics 2.0 results.
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
versionset tov4show results only for applications that are on. Soface_metrics_2disappears 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_attachederror.
Migration checklist
Not a Haut.AI client yet?
Last updated