# YouCam Skills 技能包

**把 YouCam AI 装进智能体，直接当技能用。**

YouCam Skills 把 Perfect Corp. 的 YouCam AI 能力打包成可安装的 skill，放进智能体环境里。也就是说，用户用大白话就能调起真正的 YouCam API：

> "我的皮肤状态怎么样？"
"给我换这个发型试试。"
"让我在视频里试穿这件外套。"


背后的活儿都由 skill 包办：调用 API、创建任务、轮询状态、核对费用、汇报结果。每个 skill 也都能直接从 CLI 跑起来，用来测试、做自动化，或走非智能体的流程。

## Skills 技能包

YouCam Skills 仓库：[https://github.com/YouCam-API/skills](https://github.com/YouCam-API/skills)

## 安装

如果您的智能体环境支持 [Skills CLI](https://github.com/vercel-labs/skills)，可以直接从 GitHub
安装：

```
npx skills add YouCam-API/skills
```

执行后会列出本仓库的六个 skill，让您挑要装哪几个，再挑装到您已安装的
哪些智能体里（Claude Code、Cursor 等）。不想被一路追问的话，直接指定要装的
skill 和智能体：

```
npx skills add YouCam-API/skills --skill skin-analysis-expert -a claude-code
```

或者一次全装，装到所有检测到的智能体上：

```
npx skills add YouCam-API/skills --all
```

本仓库把 6 种由 AI 驱动的美妆、仪容、发型、肤质与服饰试穿体验，做成了模块化的 Agent Skill：

| Skill | 适用场景 |
|  --- | --- |
| **Skin Analysis Expert** | 一张自拍，分析 16 项肌肤困扰加肤质。可选高清/标清精度，出叠加图还是蒙版图。 |
| **Facial Consultant** | 读取面部色彩与比例，包括肤色、瞳色、眉色、唇色、发色、五官形状，以及黄金比例测量。 |
| **Beauty Advisor** | 按脸型和肤色推荐妆容，再用精选或自定义美妆特效把效果渲染到照片上。 |
| **Hair Color & Style Advisor** | 根据五官特征推荐发型与发色，再用模板、参考照、配色预设或自定义色板预览。 |
| **Hair Diagnostics** | 评估发量密度、发质、毛躁程度和发长，汇成一份报告。 |
| **Clothes Try-on Studio** | 在用户照片上虚拟试穿，可选换背景，还能生成转身、走秀、摆姿势等短动作视频。 |


## 为什么值得用

对开发者来说：

- YouCam API 的自然语言入口
- 适配智能体环境的可安装 skill 结构
- 以 CLI 优先的测试方式，用 `youcam_core.py`
- 自动跑通「上传 → 创建任务 → 轮询」流程
- 调用付费 API 前先做点数感知的检查
- 结构简单，新增或自定义 skill 很方便


对产品和营销来说：

- AI 美妆、护肤、护发与服饰试穿体验
- 基于用户照片的个性化推荐
- 一眼就看得懂的视觉预览
- 跑之前就把花费讲清楚
- 内置针对 AI 生成结果的负责任使用提示


## 工作流程

每个 skill 都走同一套流程：

1. 用户用自己的话把需求说出来。
2. 智能体挑出合适的 YouCam Skill。
3. skill 索要必需的输入，比如照片、要做的动作。
4. 运行前先检查或估算点数花费。
5. 随附的脚本上传素材并创建 API 任务。
6. 轮询任务，直到完成。
7. 结果以结构化 JSON 返回，并给出清楚的小结。


## 环境准备

需要的东西：

- Python 3
- pip
- YouCam API 密钥
- `requests`
- `PyYAML`


进入某个 skill 文件夹，运行：

```bash
python scripts/youcam_core.py setup
```

这会创建一个本地虚拟环境并装好依赖。

也可以这样：

```bash
pip install -r scripts/requirements.txt
```

API 密钥在这里申请：

https://yce.makeupar.com/api-console/

## API 密钥配置

`youcam_core.py` 会按下面的顺序找凭据：

1. 环境变量：


```bash
YOUCAM_API_KEY=your_key_here
```

1. skill 文件夹里的本地 `credentials.json` 文件：


```json
{
  "api_key": "your_key_here"
}
```

每个 skill 有自己的文件夹，所以凭据是按 skill 分别配置的。

验证密钥、查看余额，都不花点数：

```bash
python scripts/youcam_core.py validate-key
```

## 执行前先查花费

在发起付费 API 调用之前，用户或智能体可以先跑免费的预检：

```bash
python scripts/youcam_core.py cost --feature skin-analysis
python scripts/youcam_core.py credits
```

这两条命令都免费，返回定价或余额信息。

有了它，就容易搭出点数感知的流程：花多少，用户先确认。

## CLI 快速上手

直接跑一个 skill：

```bash
python scripts/youcam_core.py run \
  --feature skin-analysis \
  --src_file selfie.jpg \
  --param format=json \
  --param dst_actions='["hd_pore","hd_skin_type"]'
```

这条命令会：

- 上传源图片
- 创建 API 任务
- 轮询直到完成
- 打印结构化 JSON 输出


常用参数：

| 参数 | 作用 |
|  --- | --- |
| `--feature` | 选择要用的 YouCam 功能。 |
| `--src_file` | 主要输入图片/视频的本地路径或 URL。 |
| `--ref_file` | 可选的第二路输入，例如服装照片。 |
| `--param` | 可重复使用的键值型 API 参数。 |
| `--version` | 需要时覆盖默认 API 版本。 |


支持的素材格式通常是 JPG、JPEG 或 PNG。视频类功能可能支持 MP4。本工具不会自动转格式。

如果停止轮询时任务还在跑：

```bash
python scripts/youcam_core.py status \
  --feature skin-analysis \
  --task_id <task_id>
```

## 智能体里的体验

在支持 Skills 的智能体环境里，用户不用知道接口叫什么、参数怎么填，直接说要什么结果就行：

- "分析一下我的皮肤。"
- "给我推荐个发型。"
- "把这套衣服穿我身上，让它动起来。"
- "用这张照片看看我的头发健康情况。"


智能体会挑对 skill、收集必需的输入、确认花费、跑完 API 流程，最后交回一个看得懂的结果。

## 重要提示

所有输出均为 AI 生成，仅供参考，不构成医疗、皮肤科、美妆或专业造型建议。

结果好坏取决于：

- 照片分辨率
- 光线
- 脸部角度
- 画面清晰度
- 主体是否完整可见
- 输入格式是否在支持范围内


个别 API 字段偶尔会取不到。skill 的设计原则是缺什么就不写什么，绝不编数据。