接口总览

这是什么。 把您的商品目录交给一次精准的肤质分析来做匹配。上传您在售的护肤商品及其描述，调用时传入目录 id，接口就会在 llm_results.json 里为每一项检测出的皮肤问题返回匹配度最高的商品。

它与通用大模型推荐的区别在于输入。通用大模型靠概率和先验来推荐；Perfect AI 肤质分析先产出科学、量化的皮肤指标与真实的检测蒙版，模型再把商品同实测出的皮肤状况一一对照——可靠、快速、说得清理由，而不是统计意义上的猜测。

参数

字段	类型	必填	默认值	说明
`catalog_id`	string	是	—	来自「上传商品目录」。目录必须处于 `ready` 状态，且属于您的账号。
`top_n`	integer	否	`3`	每一类皮肤问题要推荐的商品数。最小 `1`；不能超过目录的 `sku_count`。

商品目录就是肤质分析做推荐时使用的那份商品清单。上传一次，记下它的 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 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`——两者的响应结构不同
`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 来规划您的显示尺寸。