# Endpoint Overview

## Endpoint Overview
**What it is.** A full-dimension skin report written in natural language, generated by a large language model fed your **precision AI skin analysis** together with a **professional skincare reference database**. The model does not guess at your skin — it interprets measured, quantified skin metrics and real detection masks, compares them against professional skincare data, and returns a complete report in `llm_results.json`.
**Which `dst_actions` feed each dimension of the report.** The report is only as rich as the features you request. `dst_actions` is required, and **HD and SD features cannot be mixed in one request** — pick one family.
| Report dimension | V2.1 feature | Regions returned |
|  --- | --- | --- |
| Face outline and feature localization | `pf_camera_kit: true` | — |
| Skin type | `hd_skin_type` | `whole`, `t_zone`, `u_zone` |
| T-zone vs. U-zone comparison | `hd_skin_type` | `t_zone`, `u_zone` |
| Forehead lines and frown lines | `hd_wrinkle` | `forehead`, `glabellar` |
| Crow's feet and smile lines | `hd_wrinkle` | `crowfeet`, `nasolabial` |
| Pore distribution | `hd_pore` | `forehead`, `nose`, `cheek`, `whole` |
| Skin smoothness | `hd_texture` | `whole` |

**Parameters**
| Field | Type | Default | Notes |
|  --- | --- | --- | --- |
| `language` | string enum | `enu` | `enu` `cht` `jpn` `kor` `fra` `deu` `esn` `ita` `ptb` `ind` `ara` |
| `tone` | string enum | `warm` | `warm` | `direct` — both tones stay professional |
| `country` | string | — | Adds climate and seasonal context to the report |
| `city` | string | — | Adds climate and seasonal context to the report |

Send `"advanced_report": {}` to accept every default. Omit the object entirely for no report.
* Create an AI Task


```bash
# Skin Analysis with Advanced Skin Report
curl -sS -X POST "$BASE_URL/s2s/v2.1/task/skin-analysis-report" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "src_file_url": "https://your-cdn.example.com/customer-001.jpg",
    "dst_actions": ["hd_skin_type", "hd_wrinkle", "hd_pore", "hd_texture"],
    "format": "zip",
    "pf_camera_kit": true,
    "advanced_report": {
      "language": "cht",
      "tone": "direct",
      "country": "Taiwan",
      "city": "Taipei"
    }
  }'
```

```bash
# Same call, every report default (enu / warm, no climate context)
curl -sS -X POST "$BASE_URL/s2s/v2.1/task/skin-analysis-report" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "src_file_id": "your-uploaded-file-id",
    "dst_actions": ["hd_skin_type", "hd_wrinkle", "hd_pore", "hd_texture"],
    "pf_camera_kit": true,
    "advanced_report": {}
  }'
```


---

* Polling for the Report and Recommendations

Every run answers a `BasicRunTaskResponseV2` immediately. Poll the task with the returned id; the report and the recommendations are delivered in **`llm_results.json`**.

```bash
# 1. Run the task and capture the task id
TASK_ID=$(curl -sS -X POST "$BASE_URL/s2s/v2.1/task/skin-analysis" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }' | jq -r '.data.task_id')

# 2. Poll until task_status is "success"
curl -sS -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/s2s/v2.1/task/skin-analysis/$TASK_ID"
```
`task_status` moves `running` → `success` | `error`. With `format: zip`, `results.url` is a download link valid for **2 hours**, and the ZIP contains a `skinanalysisResult` folder with `score_info.json` and every detection image. With `format: json`, `results.output` returns the scores directly in the body.


---

* Request-Field Quick Reference

| Field | Required | Notes |
|  --- | --- | --- |
| `src_file_id` / `src_file_url` | Yes (one of) | Input image, per `BasicRunTaskV2` |
| `dst_actions` | **Yes** | HD features **or** SD features — never mixed |
| `format` | No | `zip` (default) | `json` — response schema differs |
| `pf_camera_kit` | No | V2.1 addition; face outline and feature localization |
| `miniserver_args` | No | Mask overlay and HD pore/wrinkle background controls |
| `advanced_report` | No | Present → report; `{}` → all defaults; omitted → none |
| `product_recommendation` | No | Present → recommendations; needs `catalog_id` |

**Resolution.** All output images are capped at a **2560 px** long side, with automatic input resizing. If `enable_mask_overlay` is `false`, you receive the raw mask as `.png` and must composite it yourself — verify the input resolution and use 2560 px to size your display when the long side exceeds it.


---


## Description:

  - `Endpoint Overview` ()
    **What it is.** A full-dimension skin report written in natural language, generated by a large language model fed your **precision AI skin analysis** together with a **professional skincare reference database**. The model does not guess at your skin — it interprets measured, quantified skin metrics and real detection masks, compares them against professional skincare data, and returns a complete report in `llm_results.json`. **Which `dst_actions` feed each dimension of the report.** The report is only as rich as the features you request. `dst_actions` is required, and **HD and SD features cannot be mixed in one request** — pick one family. | Report dimension | V2.1 feature | Regions returned |
|  --- | --- | --- |
| Face outline and feature localization | `pf_camera_kit: true` | — |
| Skin type | `hd_skin_type` | `whole`, `t_zone`, `u_zone` |
| T-zone vs. U-zone comparison | `hd_skin_type` | `t_zone`, `u_zone` |
| Forehead lines and frown lines | `hd_wrinkle` | `forehead`, `glabellar` |
| Crow's feet and smile lines | `hd_wrinkle` | `crowfeet`, `nasolabial` |
| Pore distribution | `hd_pore` | `forehead`, `nose`, `cheek`, `whole` |
| Skin smoothness | `hd_texture` | `whole` | **Parameters** | Field | Type | Default | Notes |
|  --- | --- | --- | --- |
| `language` | string enum | `enu` | `enu` `cht` `jpn` `kor` `fra` `deu` `esn` `ita` `ptb` `ind` `ara` |
| `tone` | string enum | `warm` | `warm` | `direct` — both tones stay professional |
| `country` | string | — | Adds climate and seasonal context to the report |
| `city` | string | — | Adds climate and seasonal context to the report | Send `"advanced_report": {}` to accept every default. Omit the object entirely for no report. * Create an AI Task ```bash
# Skin Analysis with Advanced Skin Report
curl -sS -X POST "$BASE_URL/s2s/v2.1/task/skin-analysis-report" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "src_file_url": "https://your-cdn.example.com/customer-001.jpg",
    "dst_actions": ["hd_skin_type", "hd_wrinkle", "hd_pore", "hd_texture"],
    "format": "zip",
    "pf_camera_kit": true,
    "advanced_report": {
      "language": "cht",
      "tone": "direct",
      "country": "Taiwan",
      "city": "Taipei"
    }
  }'
``` ```bash
# Same call, every report default (enu / warm, no climate context)
curl -sS -X POST "$BASE_URL/s2s/v2.1/task/skin-analysis-report" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "src_file_id": "your-uploaded-file-id",
    "dst_actions": ["hd_skin_type", "hd_wrinkle", "hd_pore", "hd_texture"],
    "pf_camera_kit": true,
    "advanced_report": {}
  }'
``` --- * Polling for the Report and Recommendations Every run answers a `BasicRunTaskResponseV2` immediately. Poll the task with the returned id; the report and the recommendations are delivered in **`llm_results.json`**. ```bash
# 1. Run the task and capture the task id
TASK_ID=$(curl -sS -X POST "$BASE_URL/s2s/v2.1/task/skin-analysis" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }' | jq -r '.data.task_id')

# 2. Poll until task_status is "success"
curl -sS -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/s2s/v2.1/task/skin-analysis/$TASK_ID"
``` `task_status` moves `running` → `success` | `error`. With `format: zip`, `results.url` is a download link valid for **2 hours**, and the ZIP contains a `skinanalysisResult` folder with `score_info.json` and every detection image. With `format: json`, `results.output` returns the scores directly in the body. --- * Request-Field Quick Reference | Field | Required | Notes |
|  --- | --- | --- |
| `src_file_id` / `src_file_url` | Yes (one of) | Input image, per `BasicRunTaskV2` |
| `dst_actions` | **Yes** | HD features **or** SD features — never mixed |
| `format` | No | `zip` (default) | `json` — response schema differs |
| `pf_camera_kit` | No | V2.1 addition; face outline and feature localization |
| `miniserver_args` | No | Mask overlay and HD pore/wrinkle background controls |
| `advanced_report` | No | Present → report; `{}` → all defaults; omitted → none |
| `product_recommendation` | No | Present → recommendations; needs `catalog_id` | **Resolution.** All output images are capped at a **2560 px** long side, with automatic input resizing. If `enable_mask_overlay` is `false`, you receive the raw mask as `.png` and must composite it yourself — verify the input resolution and use 2560 px to size your display when the long side exceeds it. ---