# youcam-cli

`youcam` は [YouCam AI API](https://yce.perfectcorp.com/ai-api) のコマンドラインインターフェースです。顔と体の編集、ヘア、肌分析、メイク、バーチャル試着、背景・写真編集、画像・動画生成など、すべての AI 機能をターミナルから、API と同じモデル・同じパラメータで実行できます。タスクステータスの確認、プリセットテンプレートの参照、ユニットと各機能の消費量も参照できます。

機能の評価、統合の開発、パイプラインの自動化のいずれにも使えます。

- **YouCam API の AI 機能を評価する**: ご自身の写真で機能を実行して結果を確認できます。スタイルの比較や、機能が製品に合致するかの検証に利用できます。コードは不要です。
- **API を統合する**: コードを書く前に、任意のエンドポイントをターミナルから試せます。オプションはリクエストのフィールドと 1対1 で対応し、各機能は [API レファレンス](#available-ai-features) にリンクされています。
- **AI エージェント**: Claude Code、Cursor、Codex などのエージェントは、YouCam の全機能を通常のシェルコマンドとして利用できます。すべてのコマンドは JSON を出力し、失敗時に終了コード 1 で終了します。すべての機能とオプションは `--help` に自己説明文が含まれ、無効な値はリクエスト送信前に拒否されます。
- **自動化とバッチジョブ**: シェルスクリプト、CI パイプライン、コンテナから、商品写真やポートレートのフォルダー全体に対して機能を実行できます。ローカルファイルは CLI が自動的にアップロードするため、アップロード手順をスクリプトに書く必要はありません。


## 動作条件

- **[Node.js](https://nodejs.org/) 18 以上**（および npm）。
- [YouCam API キー](https://yce.perfectcorp.com/api-console/en/api-keys/)。


## インストール

```bash
npm install -g @youcam_cli/youcam-cli

# Verify the installation
youcam --help

# Version of the YouCam CLI
youcam --version
```

アンインストールには `npm uninstall -g @youcam_cli/youcam-cli` を実行してください。

## 認証

`youcam auth login <apiKey>` で API キーを 1 度保存すると、キーはローカルに保存され、以降のすべてのコマンドで再利用されます。

```bash
youcam auth login <apiKey>

# or explicitly with a flag
youcam auth login --api-key <apiKey>

# Remove the saved API key (logout CLI tool)
youcam auth logout

# List the available authentication options
youcam auth --help
```

`auth login` はキーをプレーンな JSON ファイル `~/.youcam-cli/credentials.json` に書き込みます：

```json
{
  "apiKey": "<your-api-key>"
}
```

- すべての `run`、`status`、`template`、`client` コマンドがこのファイルを自動的に読み取ります。
- 環境変数 `YOUCAM_CLI_API_KEY` が設定されている場合、保存されたキーより優先されます。


## クイックスタート

ユニットの確認から結果のダウンロードまで、初めての AI タスクを実行してみます。ここでは実際に 1 つのタスクを実行するため、ユニットを消費します（[機能の消費量の確認](#checking-feature-cost) を参照）。

YouCam のすべての機能はバックグラウンドタスクとして実行されます。開始すると `task_id` が返され、その `task_id` を結果が準備できるまで確認し続けます。

**1. インストールとログイン**（詳細は [インストール](#installation) と [認証](#authentication) を参照）

```bash
npm install -g @youcam_cli/youcam-cli
youcam auth login <apiKey>
```

**2. ユニットを確認する**

```bash
youcam client credit
```

レスポンス：

```json
{
  "status": 200,
  "results": [
 {
 "id": 0,
 "type": "ApiPaygToken",
 "amount": 8193,
 "amount_dec": 8193,
 "expiry": 1801958399000
 }
  ]
}
```

`amount` は各エントリのユニット数、`expiry` は失効時期（Unix エポックからのミリ秒）です。API がユニットを "credit"（クレジット）と呼んでいるため、コマンド名が `credit` になっています（[ユニットと機能の消費量](#units-and-feature-cost) を参照）。

**3. タスクを開始する**

ここでは [AI Photo Enhance](/reference/ai_photo_enhance/v1.0/paths/~1s2s~1v2.0~1task~1enhance/post) を使い、サンプル写真の解像度を 2 倍にします：

```bash
youcam run enhance --src_file "https://plugins-media.makeupar.com/strapi/assets/hair_color_03_81c0c8a3c8.jpg" --scale 2
```

レスポンス：

```json
{
  "status": 200,
  "data": {
 "task_id": "32tu4jQvRbI9NfnKlw13cls8tyT1zA2ZoOtKq-RkiTL_FrIEOLYHJX1HxYVrnWz"
  }
}
```

CLI は次のステップのコマンドも表示します。これは標準エラー出力に出力されるため、標準出力はスクリプト向けの純粋な JSON のままになります：

```
Run `youcam status enhance 32tu4jQvRbI9NfnKlw13cls8tyT1zA2ZoOtKq-RkiTL_FrIEOLYHJX1HxYVrnWz` to check the result.
```

ご自身の写真を使う場合は、ローカルパスを指定してください。例：`--src_file ./photo.jpg`。

**4. 結果を確認してダウンロードする**

```bash
youcam status enhance <task_id>
```

タスクの処理中は `task_status` が `running` です。数秒後にコマンドを再実行してください。完了すると：

```json
{
  "status": 200,
  "data": {
 "error": null,
 "results": {
 "url": "https://yce-us.s3-accelerate.amazonaws.com/ttl30/.../509f8acd-8d41-4459-aa31-1d4738d7a922.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&...&X-Amz-Expires=7200&..."
 },
 "task_status": "success"
  }
}
```

`results.url` は補正後の画像です。これは 2 時間で失効する署名付きリンク（`X-Amz-Expires=7200`）なので、早めにダウンロードしてください。

**次のステップ**

- [利用可能な AI 機能](#available-ai-features) を参照し、`youcam run <feature> --help` で各機能のオプションを確認してください。
- オプション、ファイル、JSON パラメータの仕組みは [AI タスクの実行](#running-an-ai-task) を参照してください。
- 一部の機能は顔や体を先に検出します。[前処理（顔と体の検出）](#pre-process-face-and-body-detection) を参照してください。


## ユニットと機能の消費量

ユニットは YouCam API を利用するために消費する単位で、AI 機能ごとに消費数が異なります。API でも CLI でもユニットは "credit"（クレジット）と呼ばれるため、コマンド名は `client credit` と `client credit-history` になっています。公式 FAQ の [「ユニット」とはどのような意味で、どのように使われますか？](/develop/faq) を参照してください。

### ユニットの確認

```bash
youcam client credit  # remaining units
youcam client credit-history  # unit usage history
```

### 機能の消費量の確認

大規模に実行する前に、各機能がいくつのユニットを消費するかを確認できます。

```bash
youcam client feature-cost
```

これらのコマンドは `--page_size` と `--starting_token <token>` で結果をページ分けします：

- `credit-history`: `--page_size <1-30>`、既定は 20。
- `feature-cost`: `--page_size <1-20>`、既定は 20。


> 注: [前処理](#pre-process-face-and-body-detection) の検出タスクと [プリセットテンプレートの取得](#listing-predefined-templates) はユニットを消費しません。


## コマンド概要

```
youcam <command> [options]

Commands:
  auth Manage authentication credentials
  run  Run an AI task
  status  Check the status of an AI task
  template   List predefined templates
  client  Get account/credit info
  help Display help for a command
```

すべてのコマンドとサブコマンドは `-h, --help` をサポートしており、それぞれの使い方とオプションを表示します：

```bash
youcam run --help
youcam run face-swap --help
```

結果は JSON で出力されます。リクエストが失敗すると、コマンドは終了コード 1 で終了します。

## API ↔ CLI コマンドの対応

API レファレンスのすべてのエンドポイントは、規則的な方法で CLI コマンドに対応します：

| REST エンドポイント | CLI コマンド |
|  --- | --- |
| `POST /s2s/v{ver}/task/{feature}` | `youcam run <feature> [options]` |
| `GET /s2s/v{ver}/task/{feature}/{task_id}` | `youcam status <feature> <task_id>` |
| `POST /s2s/v{ver}/task/{feature}/pre-process` | `youcam run pre-process <feature> [options]` |
| `GET /s2s/v{ver}/task/{feature}/pre-process/{task_id}` | `youcam status pre-process <feature> <task_id>` |
| `GET /s2s/v{ver}/task/template/{feature}` | `youcam template <feature> [--page_size] [--starting_token]` |
| 公開されている makeup-vto のパターンカタログ | `youcam template makeup-vto <categories...>` |
| `GET /s2s/v1.0/client/credit` | `youcam client credit` |
| `GET /s2s/v1.0/client/credit/history` | `youcam client credit-history [--page_size] [--starting_token]` |
| `GET /s2s/v2.0/credit/feature-cost` | `youcam client feature-cost [--page_size] [--starting_token]` |
| `POST /s2s/v2.0/file` + 署名付き `PUT` アップロード | ファイルオプションにローカルパスを渡すと自動実行されます（[ファイルのアップロード](#uploading-files) を参照） |


API レファレンスから `<feature>` を導くための目安：

- CLI の機能名は `{task_id}` の直前にあるパスセグメントです。例：`/s2s/v2.0/task/abs-shape/{task_id}` → `abs-shape`。
- API バージョンのプレフィックス（`v2.0`、`v2.1` など）は CLI が自動的に扱います。各コマンドはAPI レファレンスで最新の API バージョンを呼び出します。例：`skin-analysis` と `hair-transfer` は `/s2s/v2.1/...` を呼び出します。複数のエンジンバージョンがある機能は、最新版のみを提供します。例：`cloth-v4` は利用できますが `cloth-v3` はできません。
- 一部のエンドポイントには余分なパスセグメントが含まれます。それを取り除くと CLI 名になります：
| API パス | CLI コマンド |
|  --- | --- |
| `/s2s/v2.0/task/2d-vto/earring`（`necklace`、`ring`、`bracelet`、`watch` も同じ） | `youcam run earring` |
| `/s2s/v2.0/task/image-to-image/youcam`、`/text-to-image/youcam`、`/image-to-video/youcam`、`/text-to-video/youcam` | `youcam run image-to-image`、`run text-to-image`、`run image-to-video`、`run text-to-video` |
| `/s2s/v2.0/task/colorize/color-correct` | `youcam run color-correct` |
- リクエストボディのプロパティは、対応する `run` コマンドの `--<property_name>` オプションになります（[ファイルのアップロード](#uploading-files) と [JSON パラメータの渡し方](#passing-json-parameters) を参照）。`page_size` や `starting_token` などのクエリパラメータも `--<param_name>` オプションになります。


[AI Hair Color Virtual Try-On](/reference/ai_hair_color/v1.0/paths/~1s2s~1v2.0~1task~1hair-color/post) を例にすると、2 つのエンドポイントは次の通りです：

```
POST /s2s/v2.0/task/hair-color   { src_file_url | src_file_id, preset?, pattern?, palettes? }
GET  /s2s/v2.0/task/hair-color/{task_id}
```

これは次の CLI コマンドに対応します：

```bash
youcam run hair-color --src_file <url-or-path> [--preset <value> | --pattern <json> --palettes <json>]
youcam status hair-color <task_id>
```

プリセットの色を適用するには：

```bash
youcam run hair-color --src_file "https://plugins-media.makeupar.com/strapi/assets/hair_color_09_76a7a1081e.jpg" --preset "Honey Blonde"
youcam status hair-color <task_id>
```

`run` コマンドは次のリクエストボディを送信します：

```json
{
  "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/hair_color_09_76a7a1081e.jpg",
  "preset": "Honey Blonde"
}
```

代わりにカスタム色を適用するには、`pattern` と `palettes` のオブジェクトを渡します：

```bash
youcam run hair-color --src_file "https://plugins-media.makeupar.com/strapi/assets/hair_color_09_76a7a1081e.jpg" \
  --pattern '{"name": "full"}' \
  --palettes '[{"color": "#8B4513", "color_intensity": 80, "shine_intensity": 50}]'
youcam status hair-color <task_id>
```

対応する JSON リクエストボディは次の通りです：

```json
{
  "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/hair_color_09_76a7a1081e.jpg",
  "pattern": { "name": "full" },
  "palettes": [{ "color": "#8B4513", "color_intensity": 80, "shine_intensity": 50 }]
}
```

`youcam run` は新しい `task_id` を出力します。それを `youcam status` に渡し、`task_status` が `success` になるまで繰り返してください。

## AI タスクの実行

各 AI 機能は `run` のサブコマンドです。オプションは機能ごとに異なります。各機能の入力は `--help` で確認してください。

```bash
youcam run <feature> [options]
```

例えば [AI Abs Filter](/reference/ai_abs_filter/v1.0/paths/~1s2s~1v2.0~1task~1abs-shape/post) を実行するには：

```bash
youcam run abs-shape --src_file "https://example.com/photo.jpg" --mode "Six-pack" --intensity 2
```

タスクの実行は `task_id` を返します。それを使って [ステータスを確認](#checking-task-status)します。

- **前処理:** 一部の機能は写真内の顔または体を先に検出するため、処理する人物を選べます。[前処理（顔と体の検出）](#pre-process-face-and-body-detection) を参照してください。
- **テンプレート:** 一部の機能は `--template_id` で既製のスタイルプリセットを受け付けます。[プリセットテンプレートの取得](#listing-predefined-templates) を参照してください。
- **検証:** オプションの値は、送信前に API スキーマに照らしてチェックされます。値の集合が固定されているオプションは `--help` にその一覧が表示され、無効な値は許可されている選択肢とともに拒否されます。


## ファイルのアップロード

画像または動画を受け取る全機能は、単一の `--src_file` オプションとして公開しています。API は相互排他な 2 つのフィールド——`src_file_url`（公開 URL）と `src_file_id`（アップロード済みファイルの ID）——を受け付けますが、CLI は渡された値に応じて正しい方を選びます：

- **公開されている URL** は `src_file_url` として送信されます。何もアップロードされません。

```bash
youcam run enhance --src_file "https://example.com/photo.jpg" --scale 2
```
- **ローカルファイルのパス** は CLI がアップロードし、タスクは `src_file_id` を使って送信されます：
  1. `POST /s2s/v2.0/file` でファイルを登録し（名前、コンテンツタイプ、サイズ）、署名付きアップロード URL と `file_id` を受け取ります。
  2. ファイルのバイト列をその署名付き URL へ `PUT` します。
  3. `run <feature>` を `src_file_id` にその `file_id` を設定して呼び出します。

```bash
youcam run enhance --src_file ./photo.jpg --scale 2
```
PowerShell や cmd では Windows のパスも使えます：

```powershell
youcam run enhance --src_file .\photo.jpg --scale 2
```


補足：

- ローカルファイルは `.jpg`、`.jpeg`、`.png`、`.mp4` のいずれかである必要があります。
- サイズ、解像度、再生時間の上限は機能に依存します。上限を超えたファイルは、`status` で `exceed_max_filesize` によりタスクが失敗します。
- 個別のアップロード用 CLI コマンドはありません。アップロードはファイルオプションを通じてのみ行われます。


### その他のファイルオプション

`--src_file` に加え、一部の機能は追加の画像（マスク、参照写真、商品写真）を受け取ります。ルールは同じです。公開 URL またはローカルパスを渡すと、ローカルパスは CLI がアップロードします。

| オプション | 内容 | 値の数 | 使用する機能 |
|  --- | --- | --- | --- |
| `--src_file <input>` | 主な元になる写真または動画 | 単一 | ほとんどの機能 |
| `--src_files <inputs...>` | 複数の元写真 | 複数 | `hair-frizziness-detection`、`hair-type-detection`、`image-to-image` |
| `--ref_file <input>` | 手本とする参照画像（例: メイクのスタイル、衣装、商品） | 単一 | `bag`、`cloth-v4`、`eye-color-vto`、`hair-transfer`、`hat`、`mu-transfer`、`ai-nail`、`scarf`、`shoes-transfer`、`bg-replace-vid`、`face-swap-vid` |
| `--ref_files <inputs...>` | 複数の参照画像（例: 対象 1 人につき 1 枚の顔、商品写真） | 複数 | `bracelet`、`earring`、`face-swap`、`nail-vto`、`necklace`、`ring`、`watch` |
| `--msk_file <input>` | 元画像に対するマスク。白が変更する領域、黒がそのまま残す領域です | 単一 | `generative-fill`、`obj-replace`、`obj-rem-vid` |
| `--srcmsk_file <input>` | 元画像内の対象部位（例: 耳、首、手首）を切り出すマスク | 単一 | `bracelet`、`earring`、`necklace`、`ring`、`watch` |
| `--refmsk_files <inputs...>` | 各 `--ref_files` エントリに対応するマスクを同じ順番で | 複数 | `bracelet`、`earring`、`ring`、`watch` |


`...` の付いたオプションは、1 つのフラグの後に複数の値をスペース区切りで受け取ります（カンマ区切りではありません）：

```bash
youcam run face-swap \
  --src_file group-photo.jpg \
  --ref_files person-a.jpg person-b.jpg \
  --face_mapping '[{"index":0,"position":0},{"index":1,"position":1}]'
```

複数の値を取るオプションに公開 URL とローカルパスが混在する場合（例：`--ref_files https://example.com/a.jpg ./b.jpg`）、その中のすべてのファイルがアップロードされます（URL も含まれます）。CLI は各 URL をダウンロードし、ローカルファイルと同じようにアップロードしたうえで、すべてをファイル ID（例：`ref_file_ids`）として送信します。その場合、URL は JPG、PNG、MP4 を配信している必要があります。URL を URL のまま送信したい場合は、そのオプションに URL のみを渡してください。

各機能がこれらのうちどれを受け付けるかは `youcam run <feature> --help` で確認できます。

## オプションの記述形式

以下に挙げる形式はいずれも同等です。お好みのものを使ってください：

```bash
youcam run skin-simulation --src_file https://example.com/face.png --acne 1
youcam run skin-simulation --src_file=https://example.com/face.png --acne=1
youcam run skin-simulation --src_file="https://example.com/face.png" --acne="1"
```

- クォートが必要になるのは、値にスペースやシェルが特別に扱う文字が含まれる場合です（例: URL 内の `&`、JSON など）。
- 複数の値を取るオプションは、1 つのフラグの後にスペース区切りで並べるか、フラグを繰り返して指定します：
  - `--src_files a.jpg b.jpg`
  - `--src_files=a.jpg --src_files=b.jpg`
  - `--src_files=a.jpg b.jpg` は不正のため拒否されます。


## JSON パラメータの渡し方

`--help` で `<value>` ではなく `<json>` と表示されるオプションは、API リクエストボディ内の `object` または `array` フィールドに対応します。構造全体を 1 つの JSON 値として渡してください：

- インラインの JSON、例：`--pattern '{"name":"full"}'`
- `.json` ファイルへのパス、例：`--effects ./effects.json`
- `-` で標準入力から JSON を読み込む、例：`cat effects.json | youcam run makeup-vto --src_file photo.jpg --effects -`


**インライン JSON のクォーティング：**

```bash
# bash / zsh / macOS / Linux / Git Bash: single quotes protect the double quotes
youcam run hair-color --src_file photo.jpg --pattern '{"name":"full"}' --palettes '[{"color":"#8B4513","color_intensity":80,"shine_intensity":50}]'

# Windows PowerShell: escape the inner double quotes
youcam run hair-color --src_file photo.jpg --pattern '{\"name\":\"full\"}' --palettes '[{\"color\":\"#8B4513\",\"color_intensity\":80,\"shine_intensity\":50}]'
```

**ネストされたオブジェクトと配列：** `hair-color` の `--pattern` は `object`、`--palettes` は `{color, color_intensity, shine_intensity}` オブジェクトの `array` です（full モードなら 1 つ、ombre モードなら 2 つ）：

```bash
youcam run hair-color \
  --src_file photo.jpg \
  --pattern '{"name":"full"}' \
  --palettes '[{"color":"#FF5733","color_intensity":80,"shine_intensity":50}]'
```

`photo.jpg` がアップロードされて `src_file_id` に解決されると、CLI は `POST /s2s/v2.0/task/hair-color` へ次のボディを送信します：

```json
{
  "src_file_id": "<file_id from the upload>",
  "pattern": {
 "name": "full"
  },
  "palettes": [
 {
 "color": "#FF5733",
 "color_intensity": 80,
 "shine_intensity": 50
 }
  ]
}
```

各 `--<option> <json>` の値は、そのままそのプロパティの値として使われます。`--pattern` は `pattern` オブジェクトに、`--palettes` は `palettes` 配列になります。名前の変更も構造の変更もされず、指定しなかったオプションにデフォルト値が追加されることもありません。

**深くネストされた配列：** `makeup-vto` の `--effects` はエフェクトオブジェクトの配列で、一部のオブジェクトは独自の `pattern` と `palettes` を持ちます。複数行の JSON も使えます：

```bash
youcam run makeup-vto --src_file photo.jpg --effects '[
  {"category":"skin_smooth","skinSmoothStrength":55,"skinSmoothColorIntensity":45},
  {"category":"blush","pattern":{"name":"1color1"},"palettes":[
 {"color":"#e19f9f","texture":"matte","colorIntensity":60}
  ]}
]'
```

`1color1` のようなパターン名は `youcam template makeup-vto` から取得します（[makeup-vto パターン名の取得](#listing-makeup-vto-pattern-names) を参照）。

不正な JSON や型の合わない値は、リクエスト送信前に拒否され、問題のあるフィールド名が示されます。例：`Invalid value for --palettes: [{"color":123}] (0.color: Invalid input: expected string, received number)`。

## タスクステータスの確認

```bash
youcam status <feature> <task_id>
# or
youcam status <feature> --task_id <task_id>
```

例：

```bash
youcam status abs-shape 1234567890abcdef
```

`task_status` が `success`（または `error`）になるまでポーリングしてください。その時点でレスポンスには結果（出力ファイルの URL など）が含まれます。前処理タスクの場合は `youcam status pre-process <feature> <task_id>` を使ってください。

## 前処理（顔と体の検出）

> 前処理タスクはユニットを消費しません。ユニットを消費するのはメインタスクのみです。


以下の機能では、1 枚の写真に複数の人物が写っていることがあるため、処理する人物を選びます。`youcam run pre-process <feature>` は写真内の顔または体を検出し、リストとして返します。各検出結果はリスト中の位置によって番号が振られます：1 番目が `0`、2 番目が `1`、以下同です。

1. 検出する：`youcam run pre-process <feature> --src_file <photo>` が `task_id` を返します。
2. 検出結果を読む：`youcam status pre-process <feature> <task_id>` で検出された顔または体の一覧を取得します。一覧の形は機能によって異なります。`body-reshape` は画像サイズに対する相対値（`0`–`1`）のボックスを含む `results.result[]` を返し、`face-swap` はピクセル単位のボックス `[x1, y1, x2, y2]`（左上と右下の角）を含む `results.faces[].bbox` を返します。
3. 同じ写真に対して機能を実行し、選んだ番号を下の表のオプションで渡します：


| 機能 | 検出された顔または体の番号を受け取るオプション |
|  --- | --- |
| `body-reshape` | `--index <number>` |
| `face-lift` | `--index <number>` |
| `face-reshape` | `--index <number>` |
| `fitzpatrick-scale-analyzer` | `--index <number>` |
| `teeth-whiten` | `--index <number>` |
| `face-swap` | 各 `--face_mapping` エントリの `"position"`。同じエントリの `"index"` は、どの `--ref_files` 画像を使うかを示します |


例えば `youcam run face-lift --src_file <photo> --index 1 ...` は、2 番目に検出された顔をリフトします。実際の出力を伴う一連の実行は [使用例のワークフロー](#example-workflow) を参照してください。

## プリセットテンプレートの取得

一部の機能には既製のテンプレート（スタイルやルックのプリセット）が搭載されており、パラメータを自作する代わりに `--template_id` で参照できます。

```bash
youcam template <feature> [--page_size <1-20>] [--starting_token <token>]
```

`<feature>` には次のいずれかを指定します：

| カテゴリー | 機能 |
|  --- | --- |
| ヘア＆ヒゲ | `hair-bang`、`hair-curl`、`hair-ext`、`hair-transfer`、`hair-vol`、`beard-style` |
| メイク＆試着 | `look-vto`、`fabric` |
| 画像 | `ai-avatar`、`ai-studio`、`headshot`、`bg-replace` |
| 動画 | `video-trans` |


`makeup-vto` のパターンの詳細は [makeup-vto パターン名の取得](#listing-makeup-vto-pattern-names) を参照してください。

例：

```bash
youcam template ai-avatar --page_size 10
youcam run ai-avatar --src_file ./photo.jpg --template_id <id> --output_count 1
```

レスポンスの `next_token` を `--starting_token` として渡すと、次のページを取得できます。

`ai-avatar` タスクが成功すると、`youcam status ai-avatar <task_id>` は `results.output[].url` に生成された画像を一覧します。出力 1 件ごとに 1 エントリです。

### makeup-vto パターン名の取得

`makeup-vto` のエフェクトは名前によって形状を選びます。例：チークなら `"pattern":{"name":"1color1"}`、リップカラーなら `"shape":{"name":"plump"}`。各エフェクトカテゴリーで有効な名前を取得できます：

```bash
youcam template makeup-vto <categories...>
```

`blush`、`bronzer`、`contour`、`eyebrows`、`eyeliner`、`eyeshadow`、`eyelashes`、`lipshape`、`lipliner`、`highlighter` のうち 1 つ以上を指定します（同じ名を `--category` の後に並べることもできます）。最低 1 つは必須です。これらのカタログは公開されているため、取得にユニットは不要です。

```bash
youcam template makeup-vto blush lipshape
```

結果はカテゴリーごとにまとまります。パターンの名前として各エントリの `label` を使用してください。`colorNum`（blush、eyeliner、eyeshadow のみ）は、そのパターンが必要とする `palettes` の数です：

```json
{
  "blush": [
 {
 "category": "1 color",
 "label": "1color1",
 "thumbnail": "https://app-cdn-01.makeupar.com/.../a53cd4f4-43b6-4e19-b85a-ec7a95c6a47f.jpg",
 "tags": [
  { "id": 100, "name": "Blush 3D" },
  { "id": 103, "name": "Oblong" }
 ],
 "colorNum": 1
 }
  ],
  "lipshape": [
 {
 "category": "general",
 "label": "original",
 "thumbnail": "https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/original.png",
 "tags": []
 }
  ]
}
```

取得できなかったカテゴリーは `{ "error": "..." }` として表示され、コマンドは終了コード 1 で終了します。

## 利用可能な AI 機能

以下のいずれかを `<feature>` として `run` と `status` に指定してください。それぞれ API レファレンスのページにリンクしています。検出ステップがある機能は[前処理（顔と体の検出）](#pre-process-face-and-body-detection)を、`youcam template` が使える機能は[プリセットテンプレートの取得](#listing-predefined-templates)を参照してください。

### メイク

- [makeup-vto](/reference/makeup_vto/v1.0/paths/~1s2s~1v2.0~1task~1makeup-vto/post)
  - [パターン名](#listing-makeup-vto-pattern-names)
- [mu-transfer](/reference/ai_makeup_transfer/v1.0/paths/~1s2s~1v2.0~1task~1mu-transfer/post)
- [look-vto](/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1look-vto/post)
- [eye-color-vto](/reference/ai_eye_color_lens/v1.0/paths/~1s2s~1v2.0~1task~1eye-color-vto/post)
- [nail-vto](/reference/ai_nail_vto/v1.0/paths/~1s2s~1v2.0~1task~1nail-vto/post)
- [ai-nail](/reference/ai_nail_transfer/v1.0/paths/~1s2s~1v2.0~1task~1ai-nail/post)


### 肌、顔、体

- [face-attr-analysis](/reference/ai_face_analyzer/v1.0/paths/~1s2s~1v2.0~1task~1face-attr-analysis/post)
- [skin-analysis](/reference/ai_skin_analysis/)
- [skin-tone-analysis](/reference/ai_skin_tone_analysis/v1.0/paths/~1s2s~1v2.0~1task~1skin-tone-analysis/post)
- [fitzpatrick-scale-analyzer](/reference/ai_fitzpatrick_skin_type/v1.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer/post)
- [skin-simulation](/reference/ai_skin_simulation/v1.0/paths/~1s2s~1v2.0~1task~1skin-simulation/post)
- [abs-shape](/reference/ai_abs_filter/v1.0/paths/~1s2s~1v2.0~1task~1abs-shape/post)
- [aging](/reference/ai_aging_simulation/v1.0/paths/~1s2s~1v2.0~1task~1aging/post)
- [body-reshape](/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape/post)
- [breast-shape](/reference/ai_breast_augmentation/v1.0/paths/~1s2s~1v2.0~1task~1breast-shape/post)
- [face-lift](/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift/post)
- [face-reshape](/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape/post)
- [ai-smile](/reference/ai_smile/v1.0/paths/~1s2s~1v2.0~1task~1ai-smile/post)
- [teeth-whiten](/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten/post)


### ヘア＆ヒゲ

- [hair-density-detection](/reference/ai_hair_density_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-density-detection/post)
- [hair-frizziness-detection](/reference/ai_hair_frizziness_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-frizziness-detection/post)
- [hair-length-detection](/reference/ai_hair_length_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-length-detection/post)
- [hair-type-detection](/reference/ai_hair_type_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-type-detection/post)
- [hair-bang](/reference/ai_bangs/v1.0/paths/~1s2s~1v2.0~1task~1hair-bang/post)
- [hair-color](/reference/ai_hair_color/v1.0/paths/~1s2s~1v2.0~1task~1hair-color/post)
- [hair-curl](/reference/ai_wavy_hair/v1.0/paths/~1s2s~1v2.0~1task~1hair-curl/post)
- [hair-ext](/reference/ai_hair_extension/v1.0/paths/~1s2s~1v2.0~1task~1hair-ext/post)
- [hair-transfer](/reference/ai_hairstyle/v2.1/paths/~1s2s~1v2.1~1task~1hair-transfer/post)
- [hair-vol](/reference/ai_hair_volume/v1.0/paths/~1s2s~1v2.0~1task~1hair-vol/post)
- [beard-style](/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1beard-style/post)


### バーチャル試着

- [earring](/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring/post)
- [necklace](/reference/ai_necklace/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1necklace/post)
- [ring](/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1ring/post)
- [bracelet](/reference/ai_bracelet/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1bracelet/post)
- [watch](/reference/ai_watch/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1watch/post)
- [bag](/reference/ai_bag/v2.0/paths/~1s2s~1v2.0~1task~1bag/post)
- [hat](/reference/ai_hat/v2.0/paths/~1s2s~1v2.0~1task~1hat/post)
- [scarf](/reference/ai_scarf/v2.0/paths/~1s2s~1v2.0~1task~1scarf/post)
- [cloth-v4](/reference/ai_clothes/v4.0/paths/~1s2s~1v2.0~1task~1cloth-v4/post)
- [fabric](/reference/ai_fabric/v1.0/paths/~1s2s~1v2.0~1task~1fabric/post)
- [shoes-transfer](/reference/ai_shoes/v3.0/paths/~1s2s~1v2.0~1task~1shoes-transfer/post)


### 画像

- [enhance](/reference/ai_photo_enhance/v1.0/paths/~1s2s~1v2.0~1task~1enhance/post)
- [lighting](/reference/ai_photo_lighting/v2.0/paths/~1s2s~1v2.0~1task~1lighting/post)
- [colorize](/reference/ai_photo_colorize/v1.0/paths/~1s2s~1v2.0~1task~1colorize/post)
- [color-correct](/reference/ai_color_correction/v1.0/paths/~1s2s~1v2.0~1task~1colorize~1color-correct/post)
- [sod](/reference/ai_background_removal/v1.0/paths/~1s2s~1v2.0~1task~1sod/post)
- [bg-blur](/reference/ai_photo_background_blur/v2.0/paths/~1s2s~1v2.0~1task~1bg-blur/post)
- [bg-replace](/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1bg-replace/post)
- [generative-fill](/reference/ai_object_removal_pro/v4.0/paths/~1s2s~1v2.0~1task~1generative-fill/post)
- [obj-replace](/reference/ai_replace/v1.0/paths/~1s2s~1v2.0~1task~1obj-replace/post)
- [out-paint](/reference/ai_image_extender/v2.0/paths/~1s2s~1v2.0~1task~1out-paint/post)
- [image-to-image](/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-image~1youcam/post)
- [text-to-image](/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-image~1youcam/post)
- [ai-avatar](/reference/ai_avatar_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-avatar/post)
- [ai-studio](/reference/ai_studio_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-studio/post)
- [headshot](/reference/ai_headshot_generator/v1.0/paths/~1s2s~1v2.0~1task~1headshot/post)
- [wmk-removal](/reference/ai_watermark_removal/v1.0/paths/~1s2s~1v2.0~1task~1wmk-removal/post)
- [face-swap](/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap/post)


### 動画

- [bg-replace-vid](/reference/ai_video_background_replace/v1.0/paths/~1s2s~1v2.0~1task~1bg-replace-vid/post)
- [face-swap-vid](/reference/ai_video_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap-vid/post)
- [image-to-video](/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-video~1youcam/post)
- [text-to-video](/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-video~1youcam/post)
- [obj-rem-vid](/reference/ai_video_object_removal/v2.1/paths/~1s2s~1v2.0~1task~1obj-rem-vid/post)
- [video-sr](/reference/ai_video_enhancer/v1.0/paths/~1s2s~1v2.0~1task~1video-sr/post)
- [video-trans](/reference/ai_video_style_transfer/v1.0/paths/~1s2s~1v2.0~1task~1video-trans/post)


各機能が受け取る正確なパラメータは `youcam run <feature> --help` で確認してください。

## 使用例のワークフロー

[AI Body Reshape](/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape/post) を最初から最後まで説明します。写真内の体を検出し、1 人を選び、補正し、結果を取得します。以下のリクエストボディとレスポンスボディは、このサンプル写真を使った実際の実行で取得したものです：

**1. 検出（前処理）タスクを開始する**

```bash
youcam run pre-process body-reshape \
  --src_file "https://plugins-media.makeupar.com/strapi/assets/body_reshape_01_d10c50c97d.jpg"
```

レスポンス：

```json
{
  "status": 200,
  "data": {
 "task_id": "CKPWaMO-olxd1ECr_3tTDXW5Gu_tQw0EKgN0-dU27zSyXhV8cJR2TzYLMhDqD"
  }
}
```

**2. 検出された体を取得する**

```bash
youcam status pre-process body-reshape CKPWaMO-olxd1ECr_3tTDXW5Gu_tQw0EKgN0-dU27zSyXhV8cJR2TzYLMhDqD
```

レスポンス：

```json
{
  "status": 200,
  "data": {
 "error": null,
 "results": {
 "result": [
  {
  "left": 0.35347824096679686,
  "top": 0.022326231002807617,
  "width": 0.3041056156158447,
  "height": 0.951037073135376
  }
 ],
 "timed": 4565
 },
 "task_status": "success"
  }
}
```

`results.result` の各エントリは検出された 1 人の人物で、画像サイズに対する相対値（`0`–`1`）のバウンディングボックスで表されます。配列内の位置が次に渡す `--index` です。この写真では人物が 1 人のため、インデックスは `0` です。

**3. 選んだ人物に対してメインタスクを実行する**

```bash
youcam run body-reshape \
  --src_file "https://plugins-media.makeupar.com/strapi/assets/body_reshape_01_d10c50c97d.jpg" \
  --version 1.0 \
  --index 0 \
  --features '{"slim": 20}'
```

レスポンス：

```json
{
  "status": 200,
  "data": {
 "task_id": "ZV3WIzcB1rk7I5o8hMxKP5VdgIEpnHf7VOpsk1YC76tZy2Wur0lg4Bunb3KY-7Qa"
  }
}
```

**4. 完了までメインタスクをポーリングする**

```bash
youcam status body-reshape ZV3WIzcB1rk7I5o8hMxKP5VdgIEpnHf7VOpsk1YC76tZy2Wur0lg4Bunb3KY-7Qa
```

タスクの実行中は `task_status` が `running` です。数秒ごとにコマンドを繰り返してください。成功すると（`GET /s2s/v2.0/task/body-reshape/{task_id}`）：

```json
{
  "status": 200,
  "data": {
 "error": null,
 "results": {
 "url": "https://yce-us.s3-accelerate.amazonaws.com/ttl30/.../0b333891-60be-4cd1-81cd-7d8cae35b3eb.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&...&X-Amz-Expires=7200&...",
 "timed": 12131,
 "slim": true
 },
 "task_status": "success"
  }
}
```

`results.url` は補正後の画像です。これは期限付きの署名付きリンク（`X-Amz-Expires=7200`、つまり 2 時間）なので、タスク成功後早めにダウンロードしてください。

## デバッグガイド

CLI は標準的な YouCam API リクエストを送信するため、API ドキュメントの内容がそのままあてはまります。[レート制限](/develop/rate_limit)、[エラーコード](/develop/error_codes)、[ファイル保持期間](/develop/file_retention_period)は同じです。API 側の [デバッグガイド](/develop/debugging_guide) も参照してください。

### エラーが表れる場所

問題は 3 の地点で発生し得ます：

| 失敗する場所 | 終了コード | 標準出力 | 標準エラー出力 | 参照 |
|  --- | --- | --- | --- | --- |
| 送信前に CLI がコマンドを拒否する | `1` | 空 | エラーメッセージ | [CLI のエラー](#cli-errors) |
| API がリクエストを拒否する | `1` | `status`、`error`、`error_code` を含む JSON | 空 | [API リクエストのエラー](#api-request-errors) |
| タスクは実行されたが失敗する | `0` | `"task_status": "error"`、`data.error` のコード、`data.error_message` の説明を含む JSON | 空 | [タスクのエラー](#task-errors) |


タスクが失敗しても終了コードは `0` になります。`status` リクエスト自体は成功しているためです。スクリプトは終了コードだけでなく `data.task_status` を確認する必要があります。

### レート制限

[API のレート制限](/develop/rate_limit) はすべての `youcam` コマンドに適用されます：

- **IP アドレスごと:** 300 秒あたり最大 250 リクエスト。
- **アクセストークン（API キー）ごと:** 300 秒あたり最大 250 リクエスト。
- 両方の制限を満たす必要があります。いずれかを超えたリクエストは `429 Too Many Requests` となり、CLI は終了コード `1` で終了します。
- 推奨されるペースは約 5 リクエスト/秒です。


ほとんどのコマンドは 1 回の API リクエストを送信します。ローカルファイルを使う `run` は、タスクのリクエストに加えてファイル 1 件につき 1 回の `POST /s2s/v2.0/file` を送信します。ポーリングもカウントされます——複数のタスクを毎秒確認すると、制限はすぐに消費されます。数秒ごとにポーリングし、`429` を受けたら、即座に再試行するのではなく、遅延を伸ばしながら再試行してください。

### CLI のエラー

これらはタスクのリクエスト送信前に検出されるため、ユニットを消費しません。

| CLI のエラーメッセージ | 考えられる原因 | 解決方法 |
|  --- | --- | --- |
| `Not authenticated. Run: youcam auth login <apiKey>, or set YOUCAM_CLI_API_KEY` | 保存された API キーがなく、`YOUCAM_CLI_API_KEY` も未設定または空 | `youcam auth login <apiKey>` を実行するか、`YOUCAM_CLI_API_KEY` を設定します |
| `Invalid credentials file at <path>. Re-run: youcam auth login <apiKey>` | `credentials.json` が有効な JSON ではないか、`apiKey` が空または文字列ではない | `youcam auth login <apiKey>` を実行します。ファイルは上書きされます |
| `Can't log out: credentials file at <path> is invalid. Fix or delete it by hand` | `youcam auth logout` が同じく不正な `credentials.json` を検出し、変更しなかった | ファイルを `{ "apiKey": "<your-api-key>" }` の形に修正してから再度ログアウトするか、ファイルを削除します |
| `error: required option '--scale <value>' not specified` | 必須のオプションが指定されていない | 追加してください。`youcam run <feature> --help` にすべてのオプションが並びます |
| `error: option '--scale <value>' argument '9' is invalid. Allowed choices are 1, 2, 4.` | 値が許可された選択肢のいずれでもない | 列挙された値のいずれかを使ってください |
| `Invalid value for --page_size: 99 (Too big: expected number to be <=20)` | 値の型が不正または範囲外です。JSON オプションの場合は、メッセージにフィールド名が含まれます | 値を修正してください。JSON のクォーティングは [JSON パラメータの渡し方](#passing-json-parameters) を参照 |
| `error: unknown option '--bogus'` | そのオプションがその機能に存在しないか、つづりが誤っている | `--help` でつづりを確認してください。オプションは snake_case です（例: `--src_file` であり `--src-file` ではありません） |
| `ENOENT: no such file or directory, open '...'` | ローカルファイルのパスが誤っている | パスを確認してください。相対パスは現在のディレクトリが始点です。スペースを含むパスはクォートしてください |
| `Unsupported file type "unknown" for ./notes.txt. Supported types: image/jpeg, image/png, video/mp4` | ローカルファイルが JPG、PNG、MP4 ではない | ファイルを変換するか、公開 URL を渡してください |
| `Missing task ID. Usage: status <feature> <task_id> (or --task_id <value>)` | `status` をタスク ID なしで実行した | `run` が出力した `task_id` を渡してください |


### API リクエストのエラー

API がリクエストを拒否しました。CLI は API のレスポンスを標準出力に出力します。例：

```json
{
  "status": 400,
  "error": "This task ID doesn't exist, or the task has expired.",
  "error_code": "InvalidTaskId"
}
```

| ステータス | `error_code` | 考えられる原因 | 解決方法 |
|  --- | --- | --- | --- |
| `400` | `InvalidTaskId` | タスク ID を誤って入力した、別の機能に属している（例：`run enhance` のタスクを `status hair-color` で確認した）、または `task_id` が有効な期間である 30 日を経過している | `status` では `run` と同じ機能名を使ってください。前処理タスクは `youcam status pre-process <feature> <task_id>` を使います。タスク開始から 30 日以内に確認してください |
| `401` | `InvalidAccessToken` | 保存された API キーが誤っているか、有効ではなくなっている | [API コンソール](https://yce.perfectcorp.com/api-console/en/api-keys/) からキーをコピーし、`youcam auth login` を再実行します。使用例の行にある `<` `>` をキーに含めないでください |
| `429` | — | IP アドレスまたは API キーに対するリクエストが多すぎます | ペースを落とし、遅延を伸ばしながら再試行してください。[レート制限](#rate-limits) を参照 |


### タスクのエラー

タスクは受け付けられましたが、AI エンジンが処理できませんでした。`youcam status` は `"task_status": "error"` を返し、コードは `data.error`、説明は `data.error_message` に入ります。コードは API の [エラーコード](/develop/error_codes) ページで確認してください。一部の機能には追加のコードがあり、その機能の API レファレンスページの「ファイル仕様とエラー」に、サイズ・解像度・ポーズの制限とともに掲載されています。

### 期限切れの結果リンク

結果の URL（例：`results.url`、`ai-avatar` の `results.output[].url`）は、タスク成功後 2 時間利用できます。期限切れの場合は `youcam status <feature> <task_id>` を再実行すると新しいリンクが取得できます。これはタスク作成後 30 日間有効です。結果は 30 日後に削除されるため、残しておきたいものはそれまでにダウンロードしてください。

## ヘルプの表示

```bash
youcam help
youcam help <command>
youcam <command> <subcommand> --help # e.g., youcam run pre-process --help
```