接口总览

这是什么。 一次调用同时拿到「AI 肤质分析 + 高级测肤报告 + 商品推荐」。您会得到那份精准报告——它建立在实测皮肤指标与专业护肤参考数据库之上——再加上完全从您自家商品里给出的推荐，只需一个请求、一次轮询流程。

一个接口调用就把整个闭环走完：既有科学、高度可靠、精准的肤质分析报告，又有完全基于您的商品目录的商品推荐。商品曝光与用户黏性一次兼顾，用户体验从头到尾不断档。

商品目录就是肤质分析做推荐时使用的那份商品清单。上传一次，记下它的 catalog_id，之后每次测肤都传入这个 id。目录归属于您的账号，不属于某一个 API 密钥——账号下的每个密钥（包括项目密钥）看到的都是同一批目录，轮换密钥或删除密钥都不会影响它们。上传与存储目录完全免费。

目录文件要求

项目	取值
格式	带表头行的 CSV
编码	UTF-8，带或不带 BOM 皆可（Excel 的"CSV UTF-8"会带上 BOM）
文件大小上限	5 MB
SKU 数量上限	除文件大小外没有限制
必填栏位	`product_id`、`product_name`、`product_description`

其他栏位会被忽略，但仍计入 5 MB 的大小限制。取值中包含逗号或换行时，必须按标准 CSV 的规则加引号。每一行非空的数据行算作一个 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`——两者的响应结构不同
`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 来规划您的显示尺寸。