# 查詢肌膚檢測任務的狀態。

AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 `success` 或 `error` 通知後，使用收到的 `task_id` 查詢任務結果。設定與驗證細節請見 [webhook 整合指南](/develop/webhook)。
若您的整合不支援 webhook 或無法使用 webhook，請實作輪詢。送出 AI 任務後，以固定間隔（例如每 10 秒）輪詢狀態端點，直到任務狀態為 `success` 或 `error`。

Endpoint: GET /s2s/v2.0/task/skin-analysis/{task_id}
Security: BearerAuthenticationV2

## Security:

  - `BearerAuthenticationV2` (unknown)
    http bearer

## Path parameters:

  - `task_id` (string, required)
    要查詢的任務 ID

## Response 200:

  - `200` (unknown)
    成功查詢肌膚檢測任務的狀態

## Response 200 fields (application/json):

  - `status` (integer)
    回應狀態
    Example: 200

  - `data` (object)

  - `data.task_status` (string)
    這個任務的狀態
    Enum: "running", "success", "error"

  - `data.error` (string)
    錯誤：
- `error_exceed_max_image_size`  - 輸入圖片尺寸超過上限
- `exceed_max_filesize` - 輸入檔案大小超過上限
- `invalid_parameter` - 參數值無效
- `error_download_image` - 下載來源圖片錯誤
- `error_download_mask` - 下載遮罩圖片錯誤
- `error_decode_image` - 解析來源圖片錯誤
- `error_decode_mask` - 解析遮罩圖片錯誤
- `error_nsfw_content_detected` - 在來源圖片中偵測到 NSFW 內容
- `error_no_face` - 來源圖片未偵測到臉部
- `error_pose` - 無法偵測來源圖片的姿势
- `error_face_parsing` - 無法對來源圖片進行臉部分割
- `error_inference` - 推論流程錯誤
- `exceed_nsfw_retry_limits` - 超過重試上限以避免產生 NSFW 圖片
- `error_upload` - 上傳結果圖片錯誤
- `unknown_internal_error` - 其他
    Enum: "error_exceed_max_image_size", "exceed_max_filesize", "invalid_parameter", "error_download_image", "error_download_mask", "error_decode_image", "error_decode_mask", "error_nsfw_content_detected", "error_no_face", "error_pose", "error_face_parsing", "error_inference", "exceed_nsfw_retry_limits", "error_upload", "unknown_internal_error"

  - `data.error_message` (string)
    錯誤的詳細說明

  - `data.results` (any)

  - `data.results.url` (string, required)
    下載這個結果的網址。有效期限 2 小時。回傳的 ZIP 檔案包含一個 skinanalysisResult 資料夾，內有 score_info.json 檔案，記錄所有偵測結果的分數，以及所有偵測結果的圖片。當要求進階肌膚報告或產品推薦時，該資料夾也會包含 llm_results.json。僅在格式為 `zip` 時可用。
    Example: https://example.com/sample-result-url

  - `data.results.output` (array, required)
    以 JSON 格式直接回傳在回應內容中的分析結果。當要求進階肌膚報告或產品推薦時，輸出也會有一個 `type` 為 `llm_results` 的項目；其 `mask_urls[0]` 就是 llm_results.json 的網址。僅在格式為 `json` 時可用。

  - `data.results.output.type` (string)
    肌膚檢測的項目
    Example: hd_skin_type

  - `data.results.output.region` (string)
    分析聚焦的臉部區域
    Example: whole

  - `data.results.output.raw_score` (number)
    範圍 1 到 100 的浮點數。raw_score 指 AI 模型直接預測的分數
    Example: 98.5

  - `data.results.output.ui_score` (integer)
    範圍 1 到 100 的整數。ui_score 是依據 raw_score 調整後的分數
    Example: 97

  - `data.results.output.score` (number)
    介於 1 到 100 的浮點數，代表整體膚況。
    Example: 97.66

  - `data.results.output.mask_urls` (array)
    分析過程中產生的遮罩圖片或調整尺寸後圖片的網址

## Response 400:

  - `400` (unknown)
    任務 ID 無效

## Response 400 fields (application/json):

  - `status` (integer)
    回應狀態
    Example: 400

  - `error` (string)
    Example: Invalid task ID

## Response 401:

  - `401` (unknown)
    API 金鑰無效或缺失

## Response 401 fields (application/json):

  - `status` (integer)
    回應狀態
    Example: 401

  - `error` (string)
    Example: Invalid API key

## Response 500:

  - `500` (unknown)
    任務執行逾時

## Response 500 fields (application/json):

  - `status` (integer)
    回應狀態
    Example: 500

  - `error` (string)
    Example: Task execution timed out

## Response 200 examples:

  - `format=zip 時的回應（成功）` (unknown)
    任務成功完成。結果被打包成 ZIP 檔案。

  - `format=json 時的回應（成功）` (unknown)
    任務成功完成。結果以 JSON 直接回傳，包含詳細分數與圖片網址。