---
title: "Run a Skin Analysis task."
method: POST
path: "/s2s/v2.0/task/skin-analysis"
tags: ["V2.0"]
---

# Run a Skin Analysis task.

`POST /s2s/v2.0/task/skin-analysis`

AI tasks are asynchronous. Prefer webhook-based completion handling when the feature supports webhooks. Configure your webhook endpoint, verify webhook signatures, and use the received `task_id` to query the task result after a `success` or `error` notification. See the [webhook integration guide](/develop/webhook.md) for setup and verification details.

If webhooks are not supported for the feature, or if your integration cannot use webhooks, implement polling. After starting an AI task, keep polling the task status endpoint at the given `polling_interval` until the task status is either `success` or `error`.

Do not stop polling a running task for longer than the allowed polling window. If the task is not polled in time, the task may expire; a later status check can return `InvalidTaskId` even if processing finished, and the consumed units may still be charged.

## Request body

- union
  - object — This object represents a run Skin Analysis task.
    - `src_file_url` string, required — Url of the file to run task. The url should be publicly accessible.
    - `dst_actions` string[], required — The actions for Skin Analysis. There are 2 types of features: HD and SD. You can choose one or more features, either all in SD or all in HD. Note: HD and SD features cannot be mixed. HD features: - hd_redness: Measures skin redness severity. - hd_oiliness: Determines skin oiliness level. - hd_age_spot: Detects age spots and pigmentation. - hd_radiance: Evaluates skin radiance. - hd_moisture: Assesses skin hydration levels. - hd_dark_circle: Analyzes the presence of dark circles under the eyes. - hd_eye_bag: Detects eye bags. - hd_droopy_upper_eyelid: Measures upper eyelid drooping severity. - hd_droopy_lower_eyelid: Measures lower eyelid drooping severity. - hd_firmness: Evaluates skin firmness and elasticity. - hd_texture: Analyzes overall skin texture. - hd_acne: Detects acne presence. - hd_pore: Detects and evaluates pores in different facial regions (forehead, nose, cheek, whole). - hd_wrinkle: Measures the severity of wrinkles in various facial areas (forehead, glabellar, crowfeet, periocular, nasolabial, marionette, whole). - hd_tear_trough: Detects tear trough. - hd_skin_type: Subcategories (whole, T-zone, U-zone) evaluate skin type as Normal, Oily, Dry, Combination, Redness, Dry and Redness, Oily and Redness, or Combination and Redness. SD features: - wrinkle: General wrinkle analysis. - droopy_upper_eyelid: Measures upper eyelid drooping severity. - droopy_lower_eyelid: Measures lower eyelid drooping severity. - firmness: Evaluates skin firmness and elasticity. - acne: Evaluates acne presence. - moisture: Measures skin hydration. - eye_bag: Detects eye bags. - dark_circle_v2: Analyzes dark circles. - age_spot: Detects age spots. - radiance: Evaluates skin brightness. - redness: Measures skin redness. - oiliness: Determines skin oiliness. - pore: Measures pore visibility. - texture: Analyzes overall skin texture. - tear_trough: Detects tear trough. - skin_type: Subcategories (whole, T-zone, U-zone) evaluate skin type as Normal, Oily, Dry, Combination, Redness, Dry and Redness, Oily and Redness, or Combination and Redness.
    - `miniserver_args` RunSkincareTaskMiniserverArgs
      - `enable_mask_overlay` boolean — Controls whether the mask is blended onto the image. True returns the overlaid image as a .jpg. False returns the raw mask as a .png. Default is false. <br> All output images are limited to a maximum long-side resolution of 2560 pixels. If enable_mask_overlay is not enabled, you must verify whether the input resolution exceeds 2560 and handle the mask overlay accordingly on your side. When the input image has a long side below 2560 pixels, use the original image resolution. Otherwise, use 2560 pixels to configure your display.
      - `enable_dark_background_hd_pore` boolean — Enable dark background for HD pore visualization
      - `color_dark_background_hd_pore` string — Color for HD pore dark background visualization (hex format)
      - `opacity_dark_background_hd_pore` number — Opacity for HD pore dark background visualization
      - `enable_dark_background_hd_wrinkle` boolean — Enable dark background for HD wrinkle visualization
      - `color_dark_background_hd_wrinkle` string — Color for HD wrinkle dark background visualization (hex format)
      - `opacity_dark_background_hd_wrinkle` number — Opacity for HD wrinkle dark background visualization
    - `format` 'json' | 'zip' — Response format of the analysis results. Default is 'zip'. - `zip`: Results will be packaged as a downloadable ZIP file containing a skinanalysisResult folder with score_info.json and all detection result images. The response will include a URL to download the ZIP file. - `json`: Results will be returned directly in the response body as JSON format. Note: The response schema differs between format=json and format=zip.
  - object — This object represents a run Skin Analysis task.
    - `src_file_id` string, required — ID of file to run task. File ID from upload file API.
    - `dst_actions` string[], required — The actions for Skin Analysis. There are 2 types of features: HD and SD. You can choose one or more features, either all in SD or all in HD. Note: HD and SD features cannot be mixed. HD features: - hd_redness: Measures skin redness severity. - hd_oiliness: Determines skin oiliness level. - hd_age_spot: Detects age spots and pigmentation. - hd_radiance: Evaluates skin radiance. - hd_moisture: Assesses skin hydration levels. - hd_dark_circle: Analyzes the presence of dark circles under the eyes. - hd_eye_bag: Detects eye bags. - hd_droopy_upper_eyelid: Measures upper eyelid drooping severity. - hd_droopy_lower_eyelid: Measures lower eyelid drooping severity. - hd_firmness: Evaluates skin firmness and elasticity. - hd_texture: Analyzes overall skin texture. - hd_acne: Detects acne presence. - hd_pore: Detects and evaluates pores in different facial regions (forehead, nose, cheek, whole). - hd_wrinkle: Measures the severity of wrinkles in various facial areas (forehead, glabellar, crowfeet, periocular, nasolabial, marionette, whole). - hd_tear_trough: Detects tear trough. - hd_skin_type: Subcategories (whole, T-zone, U-zone) evaluate skin type as Normal, Oily, Dry, Combination, Redness, Dry and Redness, Oily and Redness, or Combination and Redness. SD features: - wrinkle: General wrinkle analysis. - droopy_upper_eyelid: Measures upper eyelid drooping severity. - droopy_lower_eyelid: Measures lower eyelid drooping severity. - firmness: Evaluates skin firmness and elasticity. - acne: Evaluates acne presence. - moisture: Measures skin hydration. - eye_bag: Detects eye bags. - dark_circle_v2: Analyzes dark circles. - age_spot: Detects age spots. - radiance: Evaluates skin brightness. - redness: Measures skin redness. - oiliness: Determines skin oiliness. - pore: Measures pore visibility. - texture: Analyzes overall skin texture. - tear_trough: Detects tear trough. - skin_type: Subcategories (whole, T-zone, U-zone) evaluate skin type as Normal, Oily, Dry, Combination, Redness, Dry and Redness, Oily and Redness, or Combination and Redness.
    - `miniserver_args` RunSkincareTaskMiniserverArgs
      - `enable_mask_overlay` boolean — Controls whether the mask is blended onto the image. True returns the overlaid image as a .jpg. False returns the raw mask as a .png. Default is false. <br> All output images are limited to a maximum long-side resolution of 2560 pixels. If enable_mask_overlay is not enabled, you must verify whether the input resolution exceeds 2560 and handle the mask overlay accordingly on your side. When the input image has a long side below 2560 pixels, use the original image resolution. Otherwise, use 2560 pixels to configure your display.
      - `enable_dark_background_hd_pore` boolean — Enable dark background for HD pore visualization
      - `color_dark_background_hd_pore` string — Color for HD pore dark background visualization (hex format)
      - `opacity_dark_background_hd_pore` number — Opacity for HD pore dark background visualization
      - `enable_dark_background_hd_wrinkle` boolean — Enable dark background for HD wrinkle visualization
      - `color_dark_background_hd_wrinkle` string — Color for HD wrinkle dark background visualization (hex format)
      - `opacity_dark_background_hd_wrinkle` number — Opacity for HD wrinkle dark background visualization
    - `format` 'json' | 'zip' — Response format of the analysis results. Default is 'zip'. - `zip`: Results will be packaged as a downloadable ZIP file containing a skinanalysisResult folder with score_info.json and all detection result images. The response will include a URL to download the ZIP file. - `json`: Results will be returned directly in the response body as JSON format. Note: The response schema differs between format=json and format=zip.

## Response `200`

Successful execution of Skin Analysis task

- BasicRunTaskResponseV2
  - `status` integer — Response status
  - `data` object
    - `task_id` string — ID of this task. Task result is valid to query by this ID for 24 hours.

## Other responses

- `400`
- `401` — Invalid or missing API key
- `429` — Too many requests

---

[API](https://skmtc.net/perfectcorp/apis/ai-skin-analysis.md) · [All operations](https://skmtc.net/perfectcorp/apis/ai-skin-analysis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/perfectcorp/ai-skin-analysis/versions/3b5a7dcb2864/schema)