🟢API for Metrics and Submetrics

This page contains overview and OpenAPI specs of methods used to retrieve metrics and submetrics from SaaS in different scenarios.

Metrics and Submetrics are the results of image analysis performed by one or more of Algorithms on the uploaded image.

Check the Numerical Values in Algorithms Results overview for more details.

What can you do?

List metrics and submetrics for image

Top-Level Fields:

  • id: A unique identifier for this specific analysis request ("4e01deaf-200b-454e-aafb-1334d2eca38e").

  • is_ok: A boolean value indicating whether the processing was successful (true). If it's false then the algorithm calculation produced an error which can be seen in result attribute. Depending on error, the image can be reuploaded to try again if it's internal error (rare case) or it's simply can't be processed by our algorithms. If it looks like an internal error and is reproduced for all images - please contact support.

  • image_id: The unique identifier for the uploaded image ("2444fbe4-79b5-4ecb-a675-c4c0c900d586").

  • algorithm_version_id: (Deprecated) The Database / API identifier for the version of the algorithm used (51). You can use it to filter results, but it's better to use algorithm_family_tech_name.

  • creation_time: The timestamp of when the analysis was created in UTC ("2024-10-03 13:52:19").

  • application_id: The unique identifier for the application used for analysis ("8b5b3acc-480b-4412-8d2c-ebe6ab4384d7").

  • application_name: The name of the application used ("Face Skin Metrics 2.0").

  • application_description: A brief description of the application and its capabilities, including a list of visual skin features assessed during analysis.

  • application_run_id: The unique identifier for this specific run of the application ("cff0cfc5-540e-4b25-93c0-f3621356337c").

  • image_type: The type of the uploaded image, which is a selfie ("selfie").

  • algorithm_family_tech_name: The technical name of the algorithm family used ("selfie_v2.hydration").

Result Field:

  • result: An object containing detailed results from the analysis:

    • revision: The version of the algorithm being used ("master-9d0a7b4d"). This string specifies exact snapshot of algorithm code from the repository. It can be used to compare results across algorithms versions, for reporting bugs for algorithm versions. This attribute changes whenever new subversion of algorithms is published, this version is similar through all algorithms all the time.

    • image_type: Reiterates the type of image processed ("selfie").

    • area_results: An array containing results for specific areas of the image. In this example:

      • area_name: Specifies the area being analyzed (e.g., "face").

      • main_metric: The primary metric assessed for this area, which includes:

        • name: The name of the metric ("Hydration Score").

        • units: The measurement units (null in this case).

        • value: The calculated score for hydration (78).

        • tech_name: Technical name of the metric ("hydration_score").

        • widget_meta: Metadata for widget representation (null here).

        • widget_type: Type of widget used to display this metric ("bad_good_line").

        • widget_show: Indicates if the widget should be displayed (true).

      • sub_metrics: An array providing additional details on secondary metrics related to the main metric. In this example:

        • name: The name of the sub-metric ("Hydration Level").

        • units: Measurement units (null).

        • value: The assessment result for hydration level ("Normal Hydration").

        • tech_name: Technical name of the sub-metric ("hydration_level").

        • widget_meta: Metadata for widget representation (null here).

        • widget_type: Type of widget used to display this metric ("category").

        • widget_show: Indicates if the widget should be displayed (true).

    • algorithm_tech_name: The technical name of the algorithm used for analysis ("Hydration").

    • masks_restored: An array that would contain data for restored masks (not populated in this example).

    • masks_original: An array that would contain data for the original masks (not populated in this example).

This structured JSON response provides comprehensive insights into the skin analysis performed, including metrics, results, and relevant identifiers that can be utilized for further processing or reporting.

Example
{
    "id": "4e01deaf-200b-454e-aafb-1334d2eca38e",
    "result": {
        "revision": "master-9d0a7b4d",
        "image_type": "selfie",
        "area_results": [
            {
                "area_name": "face",
                "main_metric": {
                    "name": "Hydration Score",
                    "units": null,
                    "value": 78,
                    "tech_name": "hydration_score",
                    "widget_meta": null,
                    "widget_type": "bad_good_line",
                    "widget_show": true
                },
                "sub_metrics": [
                    {
                        "name": "Hydration Level",
                        "units": null,
                        "value": "Normal Hydration",
                        "tech_name": "hydration_level",
                        "widget_meta": null,
                        "widget_type": "category",
                        "widget_show": true
                    }
                ]
            }
        ],
        "algorithm_tech_name": "Hydration",
        "masks_restored": [...],
        "masks_original": [...]
    },
    "is_ok": true,
    "image_id": "2444fbe4-79b5-4ecb-a675-c4c0c900d586",
    "algorithm_version_id": 51,
    "creation_time": "2024-10-03 13:52:19",
    "application_id": "8b5b3acc-480b-4412-8d2c-ebe6ab4384d7",
    "application_name": "Face Skin Metrics 2.0",
    "application_description": "Use this application to analyze the skin’s overall condition.<br>This app will check the selfie’s image quality and assess visual skin features, such as:<ol>    <li>perceived age</li>    <li>eye age</li>    <li>skin tone</li>    <li>eye bags</li>    <li>uniformness</li>    <li>redness</li>    <li>wrinkles (deprecated)</li>    <li>pores</li>    <li>sagging (deprecated)</li>    <li>acne</li>    <li>pigmentation</li>    <li>translucency</li>    <li>hydration</li>    <li>facial landmarks</li>    <li>lines</li></ol>For the calculated metrics, the application will produce analytics, which is available in the interface. You can use this application to compare subjects, track skin dynamics over time, and get skin metric reports.",
    "application_run_id": "cff0cfc5-540e-4b25-93c0-f3621356337c",
    "image_type": "selfie",
    "algorithm_family_tech_name": "selfie_v2.hydration"
}

Critical Information

Do not rely on the order of algorithms results in the response, do not use array index to iterate over it

To find the exact algorithm result to this:

def get_algorithm_result_by_tech_name(results: list[dict], algorithm_tech_name: str):
    for result in results:
        if result["algorithm_tech_name"] == algorithm_tech_name:
           return result
           
           
response = httpx.get("https://saas.haut.ai/api/v1/.../results/")
results = response.json()
redness_result = get_algorithm_result_by_tech_name(results, "selfie_v2.redness")

List smoothed metrics for image

The algorithm smooths results by using data from the previous N images. It applies a smoothing function (like mean or linear regression) to make the output more stable and reduce noise.

• Mean Smoothing: Takes the average of the metrics from the current and previous N images.

• Linear Regression: Fits a line to the results from the previous N images to track trends and smooth the output.

This helps produce smoother, more consistent metrics by reducing sudden changes or noise in the data.

Example

  • Image 1, redness = 20

  • Image 2, redness = 40

  • Image 3, redness = 25 Smoothed redness for Images 1, 2, 3 = (20 + 40 + 25) / 3 = 28

Why do you need this?

Metrics can vary from image to image, and it's hard to understand the overall trend. Smoothed results help to understand the overall trend and make decisions based on it.

Currently we don't support smoothing for sub metrics of algorithms, only the main metrics and only for the face area (overall face metric). Maybe supported in future.

List metrics and submetrics for subject

In many cases, you will need to retrieve all the analysis results tied to a specific subject in the system, whether for further data processing, reporting, or integration with external systems.

This API allows you to fetch all results associated with a particular subject. This can be useful in a variety of scenarios, including:

  • Aggregating Data for Analysis: Developers can fetch all historical analysis results for a subject and aggregate or further process the data in their applications. For example, tracking the subject's skin condition over time or comparing different types of analyses.

  • Displaying Subject History: If you need to show a history of analyses or assessments to users in your UI, this endpoint provides the relevant data to populate those views.

  • Integrating with External Systems: This API can be used to pull results into third-party systems for further processing or storage, especially if you're building dashboards, reports, or conducting data integration.

Common Use Case Example:

For instance, if you are building an interface that shows a subject’s detailed analysis history for the past year, you can use this endpoint with a since parameter to only retrieve results from the past 12 months.

PreviousAPI for MasksNextAPI for Products Recommendation

Last updated