Analysis + Product Recommendation

操作

端點總覽

這是什麼。 把您的產品目錄交給一次精準的肌膚檢測來比對。上傳您在售的護膚產品及其說明，呼叫時傳入目錄的 id，端點就會在 llm_results.json 裡，為每一項偵測到的肌膚困擾回傳最契合的產品。

它與一般 LLM 推薦的差別在於輸入。一般 LLM 靠機率與先驗知識推薦；Perfect AI 肌膚檢測會先產出科學、量化的肌膚指標與真實的偵測遮罩，模型再把產品對照實測出來的肌膚狀況——可靠、快速、說得出理由，而不是統計意義上的猜測。

參數

欄位	類型	必填	預設值	說明
`catalog_id`	string	是	—	取自「上傳產品目錄」。該目錄必須為 `ready` 狀態，且屬於您的帳號。
`top_n`	integer	否	`3`	每一項肌膚困擾要推薦的產品數。最小 `1`；不得超過目錄的 `sku_count`。

產品目錄就是肌膚檢測進行推薦時所用的產品清單。上傳一次，記住它的 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 Analysis with Product Recommendation
curl -sS -X POST "$BASE_URL/s2s/v2.1/task/skin-analysis-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"
    ],
    "format": "zip",
    "pf_camera_kit": true,
    "product_recommendation": {
      "catalog_id": "1662043585118399001",
      "top_n": 3
    }
  }'

驗證。 下列每種情況都會回傳 400 與 error_code: InvalidParameters，而且不扣點數：

原因	`error` 訊息
有 `product_recommendation` 卻沒有 `catalog_id`	`catalog_id is required when product_recommendation is provided.`
目錄不存在、已被刪除，或屬於其他帳號	`No catalog was found with this catalog_id.`
目錄上傳時驗證失敗（`status: failed`）	`This catalog failed validation when it was uploaded and can't be used. Upload the catalog again.`
`top_n` 不是至少為 1 的整數	（常見的 `InvalidParameters` 狀況）
`top_n` 大於目錄中的產品數量	`product_recommendation.top_n can't be more than the 3 products in this catalog.`

最後一則訊息是動態產生的——它會報出目錄實際的 sku_count。請從「列出目錄」讀取 sku_count，在您的端把 top_n 收斂到它的範圍內。

輪詢取得報告與推薦

每次呼叫都會立刻回傳一個 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-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-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 來設定您的顯示尺寸。