Skin AI

Overview

The Skin AI API is a powerful tool that allows you to predict skin conditions based on images. It uses advanced machine learning models to analyze images and provide a risk assessment.

Base URL

The base URLs for the Respiratory AI API are

• PROD: https://api.prod.helfie.ai.
• DEV: https://api-dev.helfie.ai.

API Endpoints

Skin Condition Prediction Endpoint

• Endpoint: /skin/api/skin-assessment
• Method: POST
• Description: This endpoint allows you to predict skin conditions based on an image. The image is processed by our advanced machine learning models, and the prediction results are returned in the response.
• Note: Use this endpoint to detect and assess risk for lesions in one go.

Request Parameters:

• image (file): The image file to be analyzed.
• user_id (text, optional): Your unique user id
• api_key (text): A valid API key
• company_id (text, optional): Your company id
• assessment_id (string, optional): The unique UUID identifier of the assessment.
• lesion_location (string, optional): The location of the lesion on the body. Accepted values include:
  • Head, Neck, Shoulder, Chest, Left Upper Arm, Right Upper Arm, Left Forearm, Right Forearm, Right Hand/Palm, Left Hand/Palm, Abdomen, Hip, Right Thigh, Left Thigh, Right Knee, Left Knee, Right Shin, Left Shin, Right Feet, Left Feet, Upper Back, Middle Back, Lower Back, Left Rear Thigh, Right Rear Thigh, Left Rear Knee, Right Rear Knee, Left Calves, Right Calves, Right Heel, Left Heel

Example Request:

curl --location '${BASE_URL}/skin/api/skin-assessment' \
--header 'api-key: ••••••' \
--form 'assessment_id="••••••"' \
--form 'image=@"path_to_your_image.jpg"' \
--form 'user_id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"' \
--form 'lesion_location="valid_location_from_list" # Optional' \

Example Response:

{
    "highest_risk": "low",
    "image_b64": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL...",
    "risk_per_lesion": [
        {
            "bounding_box": [
                372,
                288,
                433,
                329
            ],
            "label": "low",
            "probability": 0.791
        },
        {
            "bounding_box": [
                120,
                377,
                255,
                468
            ],
            "label": "low",
            "probability": 0.925
        },
        {
            "bounding_box": [
                206,
                150,
                314,
                204
            ],
            "label": "low",
            "probability": 0.778
        },
        {
            "bounding_box": [
                294,
                264,
                335,
                286
            ],
            "label": "low",
            "probability": 0.843
        },
        {
            "bounding_box": [
                132,
                140,
                387,
                306
            ],
            "label": "low",
            "probability": 0.957
        }
    ]
}

Response Fields:

• highest_risk (string): The highest risk level detected in the image. Possible values are "low", "medium", and "high".
• image_b64 (string): The base64 encoded image with bounding boxes around the detected lesions.
• risk_per_lesion (list): A list containing the risk level of each detected lesion. Each element of the list is a dictionary with the following fields:
  • bounding_box (list): The coordinates of the bounding box around the lesion. x1, y1, x2, y2.
  • label (string): The risk level of the detected skin condition. Possible values are "low", "medium", and "high".
  • probability (float): The probability of the detected skin condition.

Predict Risk Endpoint

• Endpoint: /skin/api/predict-risk
• Method: POST
• Description: This endpoint allows you to predict the risk associated with an image of skin lesions. The image is analyzed using advanced machine learning models, and the prediction results, including risk assessments per lesion, are returned in the response. The API supports bounding box annotations and specific lesion location input for more accurate analysis.
• Note: Use this endpoint to assess risk of lesions that are already detected i.e box co-ordinates of lesions are available.

Request Parameters:

• image (file): The image file to be analyzed.
• user_id (text, optional): Your unique user id
• api_key (text): A valid API key
• company_id (text, optional): Your company id
• assessment_id (string, optional): The unique UUID identifier of the assessment.
• bounding_boxes (JSON string): A JSON-encoded string representing a list of bounding boxes (normalised values) for detected lesions in the image (e.g., "[[0.42176643, 0.20082009, 0.48312667, 0.2916758], [0.294549, 0.3887598, 0.33600146, 0.44848025]") where the format is [x1, y1, x2, y2].
• lesion_location (string, optional): The location of the lesion on the body. Accepted values include:
  • Head, Neck, Shoulder, Chest, Left Upper Arm, Right Upper Arm, Left Forearm, Right Forearm, Right Hand/Palm, Left Hand/Palm, Abdomen, Hip, Right Thigh, Left Thigh, Right Knee, Left Knee, Right Shin, Left Shin, Right Feet, Left Feet, Upper Back, Middle Back, Lower Back, Left Rear Thigh, Right Rear Thigh, Left Rear Knee, Right Rear Knee, Left Calves, Right Calves, Right Heel, Left Heel

Example Request:

curl --location '${BASE_URL}/skin/api/predict-risk' \
--header 'api-key: ••••••' \
--form 'image=@"path_to_your_image.jpg"' \
--form 'user_id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"' \
--form 'bounding_boxes="[[0.42176643, 0.20082009, 0.48312667, 0.2916758], [0.294549, 0.3887598, 0.33600146, 0.44848025], [0.5359203, 0.64596206, 0.6082273, 0.75302655]]"' \
--form 'lesion_location="valid_location_from_list" # Optional' \

Example Response

{
    "highest_risk": "high",
    "risk_per_lesion": [
        {
            "bounding_box": [
                215,
                154,
                247,
                224
            ],
            "label": "low",
            "probability": 0.86
        },
        {
            "bounding_box": [
                150,
                298,
                172,
                344
            ],
            "label": "low",
            "probability": 0.745
        },
        {
            "bounding_box": [
                274,
                496,
                311,
                578
            ],
            "label": "low",
            "probability": 0.663
        }
    ],
    "image_b64": "base64_encoded_image_string",
    "assessment_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
}

Response Fields:

• highest_risk (string): The highest risk level across all detected lesions.
• risk_per_lesion (list): A list of risk assessments per lesion, including:
  • label (string): The risk label for the lesion, possible values are "low", "medium", or "high".
  • probability (float): The probability score for the given risk label.
  • bounding_box (object): The bounding box coordinates for the lesion, structured as {"x1": int, "y1": int, "x2": int, "y2": int}.
• image_b64 (string): The base64-encoded image after processing and lesion analysis.
• assessment_id (string): A unique identifier for the risk assessment session.

Detect Lesion Endpoint

• Endpoint: /skin/api/detect-lesion
• Method: POST
• Description: This endpoint allows you to detect lesions in any image. The image is processed by our advanced machine learning models and the lesion locations are returned in the response as coordinates.
• Note: Use this endpoint to detect the lesions in image

Request Parameters:

• image (file): The image file to be analyzed.
• user_id (text, optional): Your unique user id
• api_key (text): A valid API key
• company_id (text, optional): Your company id
• assessment_id (string, optional): The unique UUID identifier of the assessment.
• lesion_location (string, optional): The location of the lesion on the body. Accepted values include:
  • Head, Neck, Shoulder, Chest, Left Upper Arm, Right Upper Arm, Left Forearm, Right Forearm, Right Hand/Palm, Left Hand/Palm, Abdomen, Hip, Right Thigh, Left Thigh, Right Knee, Left Knee, Right Shin, Left Shin, Right Feet, Left Feet, Upper Back, Middle Back, Lower Back, Left Rear Thigh, Right Rear Thigh, Left Rear Knee, Right Rear Knee, Left Calves, Right Calves, Right Heel, Left Heel

Example Request:

curl --location '${BASE_URL}/skin/api/detect-lesion' \
--header 'api-key: ••••••' \
--form 'image=@"path_to_your_image.jpg"' \
--form 'user_id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"' \
--form 'lesion_location="valid_location_from_list" # Optional' \

Example Response:

{
    "bounding_boxes": [
        [
            376,
            423,
            431,
            501
        ],
        [
            121,
            572,
            226,
            704
        ],
        [
            142,
            222,
            330,
            447
        ],
        [
            170,
            218,
            387,
            485
        ]
    ],
    "message": "Detected 4 lesion(s).",
    "assessment_id": "2702e1fd-8edc-46ff-b9a9-088d440d8b72"
}

Response Fields:

• bounding_boxes (list): A list of bounding boxes around the detected lesions. Each element of the list is a list of four coordinates (pixels) representing the bounding box. x1, y1, x2, y2.
• message (string): A user-frinedly message with the outcome.
• assessment_id (string): The unique UUID identifier of the assessment. Can be consumed by acknowledge_assessment and skin-assessment APIs