端點總覽

這是什麼。 一次呼叫同時完成肌膚檢測、進階肌膚報告與產品推薦。您拿到的是一份扎實的報告——依據實測的肌膚指標與專業護膚參考資料庫——加上完全取自您自家產品的推薦，只需要一個請求、一套輪詢流程。

一個 API 呼叫跑完整個閉環：科學、可信度高、精準的肌膚分析報告，再附上完全以您的目錄為依據的產品推薦。產品曝光與使用者回留，在同一次處理、同一段不中斷的使用者旅程中一起到位。

產品目錄就是肌膚檢測進行推薦時所用的產品清單。上傳一次，記住它的 catalog_id，之後每次肌膚檢測都傳入這個 id。目錄歸屬您的帳號，而不是某一個 API key——帳號下的每個 key（包含專案 key）看到的都是同一批目錄，輪換或刪除 key 都不會影響它們。上傳與儲存目錄是免費的。

目錄檔案需求

項目	值
格式	含標題列的 CSV
編碼	UTF-8，可含或不含 BOM（Excel 的「CSV UTF-8」會加上 BOM）
最大檔案大小	5 MB
最大 SKU 數量	除檔案大小外無限制
必要欄位	`product_id`、`product_name`、`product_description`

其他欄位會被忽略，但仍計入 5 MB 限制。含逗號或換行的值請加上引號。每個非空的資料列計為一個 SKU。

product_id,product_name,product_description
SKU-001,Hydrating Serum,"A lightweight serum for dry skin."
SKU-002,Brightening Cream,"Evens out skin tone, for daily use."
SKU-003,Barrier Repair Cream,"Rich cream for dry, redness-prone skin."

# Upload a catalog — validated in the same request
curl -sS -X POST "$BASE_URL/s2s/v2.1/product-catalog" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@catalog.csv" \
  -F "name=Summer skincare"

通過驗證的檔案會回傳 status: ready，並附上它的 catalog_id 與 sku_count——請保留這個 id：

{
  "status": 200,
  "data": {
    "catalog_id": "1662043585118399001",
    "name": "Summer skincare",
    "status": "ready",
    "created_time": 1760256000000,
    "sku_count": 3
  }
}

# List every catalog of your account, newest first (ready and failed alike)
curl -sS -H "Authorization: Bearer $API_KEY" "$BASE_URL/s2s/v2.1/product-catalog"

# Delete a catalog — immediate and permanent
curl -sS -X DELETE -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/s2s/v2.1/product-catalog/1662043585118399001"

目錄狀態與限制

狀態	意義	可用於肌膚檢測
`ready`	已上傳並通過驗證	是
`failed`	已上傳，但檔案驗證失敗	否

驗證失敗的上傳會回傳錯誤，而且仍會被記錄成一個 failed 目錄，在「列出目錄」中看得到它；錯誤內容不會帶出它的 catalog_id。每個帳號最多可保留 10 個目錄，ready 與 failed 合併計算——上傳新目錄前請先刪掉一個。要更新目錄，請上傳新檔案：每次上傳都會建立新的 catalog_id，舊目錄在您刪除前仍可使用，因此可以先確認新目錄再切換。

建立 AI 任務

# Skin Intel System — Report + Recommendations
curl -sS -X POST "$BASE_URL/s2s/v2.1/task/skin-analysis-report-recommendation" \
  -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",
      "hd_acne", "hd_redness", "hd_oiliness", "hd_moisture",
      "hd_age_spot", "hd_radiance", "hd_dark_circle", "hd_firmness",
      "hd_eye_bag", "hd_tear_trough", "hd_droopy_upper_eyelid",
      "hd_droopy_lower_eyelid"
    ],
    "format": "zip",
    "pf_camera_kit": true,
    "miniserver_args": {
      "enable_mask_overlay": true
    },
    "advanced_report": {
      "language": "enu",
      "tone": "warm",
      "country": "United States",
      "city": "New York"
    },
    "product_recommendation": {
      "catalog_id": "1662043585118399001",
      "top_n": 3
    }
  }'

輪詢取得報告與推薦

每次呼叫都會立刻回傳一個 BasicRunTaskResponseV2；用回傳的 id 輪詢任務就行，報告與推薦結果都放在 llm_results.json 裡。

# 1. Run the task and capture the task id
TASK_ID=$(curl -sS -X POST "$BASE_URL/s2s/v2.1/task/skin-analysis-report-recommendation" \
  -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-report-recommendation/$TASK_ID"

task_status 會從 running 走到 success | error。用 format: zip 時，results.url 是一條有效期限 2 小時的下載連結，ZIP 裡有一個 skinanalysisResult 資料夾，包含 score_info.json 與所有偵測結果圖片。用 format: json 時，results.output 會把分數直接回傳在回應內容中。

請求欄位速查

欄位	必填	說明
`src_file_id` / `src_file_url`	是（二者其一）	輸入圖片，規則依 `BasicRunTaskV2`
`dst_actions`	是	要全選 HD 功能，或全選 SD 功能——不可混用
`format`	否	`zip`（預設）\| `json`——兩者的回應 schema 不同
`pf_camera_kit`	否	V2.1 新增；臉部輪廓與五官定位
`miniserver_args`	否	遮罩疊加，以及 HD 毛孔／皺紋的背景控制項
`advanced_report`	否	有送就出報告；`{}` 表示全採預設值；不送就沒有報告
`product_recommendation`	否	有送就出推薦；需要 `catalog_id`

解析度。 所有輸出圖片的長邊都以 2560 px 為上限，輸入圖片會自動調整尺寸。若 enable_mask_overlay 為 false，您拿到的是原始遮罩 .png，必須自行合成——請先確認輸入解析度，長邊超過 2560 px 時，就以 2560 px 來設定您的顯示尺寸。