接口总览

这是什么。 一份覆盖全维度的皮肤报告，用自然语言写成，由大语言模型生成——喂给模型的是您的精准 AI 肤质分析结果，再加上一座专业护肤参考数据库。模型不会凭空猜测您的皮肤：它解读的是实测出来的、量化的皮肤指标与真实的检测蒙版，把它们同专业护肤数据逐一对照，最后在 llm_results.json 里返回一份完整的报告。

报告的各个维度分别由哪些 dst_actions 支撑。 您请求的分析项目决定了报告能有多丰富。dst_actions 是必填项，而且同一个请求里 HD 与 SD 项目不能混用——只能选其中一类。

报告维度	V2.1 项目	返回的区域
脸部轮廓与五官定位	`pf_camera_kit: true`	—
肤质	`hd_skin_type`	`whole`, `t_zone`, `u_zone`
T 区与 U 区对比	`hd_skin_type`	`t_zone`, `u_zone`
额头纹与眉间纹	`hd_wrinkle`	`forehead`, `glabellar`
眼角纹与法令纹	`hd_wrinkle`	`crowfeet`, `nasolabial`
毛孔分布	`hd_pore`	`forehead`, `nose`, `cheek`, `whole`
肌肤平滑度	`hd_texture`	`whole`

参数

字段	类型	默认值	说明
`language`	string enum	`enu`	`enu` `cht` `jpn` `kor` `fra` `deu` `esn` `ita` `ptb` `ind` `ara`
`tone`	string enum	`warm`	`warm` \| `direct`——两种语气都保持专业
`country`	string	—	为报告加入气候与季节背景
`city`	string	—	为报告加入气候与季节背景

传 "advanced_report": {} 就全部采用默认值；整个对象都不传，就没有报告。

创建 AI 任务

# Skin Analysis with Advanced Skin Report
curl -sS -X POST "$BASE_URL/s2s/v2.1/task/skin-analysis-report" \
  -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"],
    "format": "zip",
    "pf_camera_kit": true,
    "advanced_report": {
      "language": "cht",
      "tone": "direct",
      "country": "Taiwan",
      "city": "Taipei"
    }
  }'

# Same call, every report default (enu / warm, no climate context)
curl -sS -X POST "$BASE_URL/s2s/v2.1/task/skin-analysis-report" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "src_file_id": "your-uploaded-file-id",
    "dst_actions": ["hd_skin_type", "hd_wrinkle", "hd_pore", "hd_texture"],
    "pf_camera_kit": true,
    "advanced_report": {}
  }'

轮询获取报告与推荐

每次调用都会立刻返回一个 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" \
  -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/$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 来规划您的显示尺寸。