# YouCam スキル

**YouCam AI をドロップイン型の Agent Skills に変える。**

YouCam Skills は、Perfect Corp の YouCam AI 機能をエージェント環境向けにインストール可能なスキルとしてパッケージ化します。つまり、ユーザーは自然言語で実際の YouCam API をトリガーできます:

> 「私の肌はどんな状態ですか？」
「この髪型を私に試着して。」
「このジャケットを動画で試着させて。」


裏側では、各スキルが API 呼び出し、タスク作成、ポーリング、コストチェック、結果レポートを処理します。すべてのスキルはテスト、自動化、非エージェントのワークフローのために CLI から直接実行することもできます。

## スキル

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
```

これにより、このリポジトリの 6 つのスキルがリスト表示され、追加するものを選択できます。次に、
インストールしたエージェント（Claude Code、Cursor など）のどれに追加するかを尋ねられます。プロンプトをスキップするには、特定の
スキルと/または特定のエージェントを直接指定します:

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

または、検出されたすべてのエージェントにすべてインストールします:

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

このリポジトリは、AI によるビューティー、グルーミング、ヘア、スキン、ファッションの試着体験を 6 つ、モジュール化された Agent Skills として公開しています:

| スキル | ユースケース |
|  --- | --- |
| **Skin Analysis Expert** | 1 枚のセルフィーから 16 の肌悩みと肌タイプを分析します。HD/SD の詳細度と、オーバーレイまたはマスクの可視化を選択できます。 |
| **Facial Consultant** | 顔の色や比率を読み取ります。肌のトーン、目の色、眉の色、唇の色、髪の色、パーツの形、黄金比の測定値を含みます。 |
| **Beauty Advisor** | 顔の形と肌のトーンに基づいてメイクルックを提案し、キュレーションまたはカスタムのビューティーエフェクトを使用して結果を写真にレンダリングします。 |
| **Hair Color & Style Advisor** | 顔の特徴からヘアスタイルとカラーを提案し、テンプレート、参考写真、カラープリセット、カスタムパレットでプレビューできます。 |
| **Hair Diagnostics** | 髪の密度、タイプ、うねり、長さを評価し、結果を 1 つのレポートにまとめます。 |
| **Clothes Try-on Studio** | ユーザーの写真でのバーチャル服装試着。背景の置換や、ターン、ランウェイウォーク、ポーズなどの短いモーション動画もオプションで対応します。 |


## なぜ重要なのか

開発者向け:

- YouCam API の自然言語エントリポイント
- エージェント環境向けのインストール可能なスキル構造
- `youcam_core.py` による CLI ファーストのテスト
- アップロード → タスク作成 → ポーリングの自動フロー
- 有料 API 呼び出し前のクレジットを考慮した実行
- スキルの追加やカスタマイズのためのシンプルな拡張モデル


プロダクトおよびマーケティング用途:

- AI によるビューティー、スキンケア、ヘアケア、ファッションの試着体験
- ユーザーの写真に基づくパーソナライズされた提案
- ビジュアルプレビュー
- 実行前の明確なコストコミュニケーション
- AI 生成結果に関する責任ある利用のメッセージを内蔵


## 動作原理

各スキルは同じワークフローに従います:

1. ユーザーが普段の英語でリクエストを説明します。
2. エージェントが適切な YouCam スキルを選択します。
3. スキルが写真やターゲットアクションなどの必須入力を求めます。
4. スキルが実行前にクレジットコストを確認または見積もります。
5. 同梱のスクリプトがメディアをアップロードし、API タスクを作成します。
6. タスクは完了するまでポーリングされます。
7. 結果は構造化 JSON で返され、明確に要約されます。


## セットアップ

要件:

- Python 3
- pip
- YouCam API キー
- `requests`
- `PyYAML`


スキルフォルダ内で次を実行します:

```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. スキルフォルダ内のローカル `credentials.json` ファイル:


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

各スキルは独自のフォルダを持つため、認証情報はスキルごとに設定されます。

クレジットを消費せずにキーを検証し、残高を確認します:

```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 クイックスタート

スキルを直接実行します:

```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` | 衣服の写真などの任意の第 2 の入力。 |
| `--param` | 繰り返し指定可能なキーバリュー形式の API パラメータ。 |
| `--version` | 必要に応じてデフォルトの API バージョンを上書きします。 |


サポートされるメディア形式は通常 JPG、JPEG、PNG です。動画機能では MP4 が受け入れられる場合があります。このツールはファイルを自動的に変換しません。

ポーリングが停止した後もタスクが実行中の場合:

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

## エージェント体験

Skills をサポートするエージェント環境内で使用する場合、ユーザーは API 名やパラメータを知る必要はありません。単に結果を依頼するだけです:

- 「私の肌を分析して。」
- 「私に合った髪型を提案して。」
- 「この服装を私に着せて、動かせて。」
- 「この写真から髪の健康状態をチェックして。」


エージェントが適切なスキルを選択し、必須入力を収集し、コストを確認し、API ワークフローを実行し、理解しやすい結果を返します。

## 重要な注意事項

すべての出力は AI によって生成され、参考用です。医療的、皮膚科的、美容的、プロのスタイリングに関する助言ではありません。

結果の品質は以下に依存します:

- 写真の解像度
- ライティング
- 顔の角度
- 画像の鮮明さ
- 被写体の見え方
- サポートされる入力形式


一部の API フィールドは時々利用できない場合があります。スキルは値を捏造するのではなく、欠損データを省略するように設計されています。