youcam は YouCam AI API のコマンドラインインターフェースです。顔と体の編集、ヘア、肌分析、メイク、バーチャル試着、背景・写真編集、画像・動画生成など、すべての AI 機能をターミナルから、API と同じモデル・同じパラメータで実行できます。タスクステータスの確認、プリセットテンプレートの参照、ユニットと各機能の消費量も参照できます。
機能の評価、統合の開発、パイプラインの自動化のいずれにも使えます。
- YouCam API の AI 機能を評価する: ご自身の写真で機能を実行して結果を確認できます。スタイルの比較や、機能が製品に合致するかの検証に利用できます。コードは不要です。
- API を統合する: コードを書く前に、任意のエンドポイントをターミナルから試せます。オプションはリクエストのフィールドと 1対1 で対応し、各機能は API レファレンス にリンクされています。
- AI エージェント: Claude Code、Cursor、Codex などのエージェントは、YouCam の全機能を通常のシェルコマンドとして利用できます。すべてのコマンドは JSON を出力し、失敗時に終了コード 1 で終了します。すべての機能とオプションは
--helpに自己説明文が含まれ、無効な値はリクエスト送信前に拒否されます。 - 自動化とバッチジョブ: シェルスクリプト、CI パイプライン、コンテナから、商品写真やポートレートのフォルダー全体に対して機能を実行できます。ローカルファイルは CLI が自動的にアップロードするため、アップロード手順をスクリプトに書く必要はありません。
- Node.js 18 以上（および npm）。
- YouCam API キー。
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 度保存すると、キーはローカルに保存され、以降のすべてのコマンドで再利用されます。
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 --helpauth login はキーをプレーンな JSON ファイル ~/.youcam-cli/credentials.json に書き込みます：
{
"apiKey": "<your-api-key>"
}- すべての
run、status、template、clientコマンドがこのファイルを自動的に読み取ります。 - 環境変数
YOUCAM_CLI_API_KEYが設定されている場合、保存されたキーより優先されます。
ユニットの確認から結果のダウンロードまで、初めての AI タスクを実行してみます。ここでは実際に 1 つのタスクを実行するため、ユニットを消費します（機能の消費量の確認 を参照）。
YouCam のすべての機能はバックグラウンドタスクとして実行されます。開始すると task_id が返され、その task_id を結果が準備できるまで確認し続けます。
1. インストールとログイン（詳細は インストール と 認証 を参照）
npm install -g @youcam_cli/youcam-cli
youcam auth login <apiKey>2. ユニットを確認する
youcam client creditレスポンス：
{
"status": 200,
"results": [
{
"id": 0,
"type": "ApiPaygToken",
"amount": 8193,
"amount_dec": 8193,
"expiry": 1801958399000
}
]
}amount は各エントリのユニット数、expiry は失効時期（Unix エポックからのミリ秒）です。API がユニットを "credit"（クレジット）と呼んでいるため、コマンド名が credit になっています（ユニットと機能の消費量 を参照）。
3. タスクを開始する
ここでは AI Photo Enhance を使い、サンプル写真の解像度を 2 倍にします：
youcam run enhance --src_file "https://plugins-media.makeupar.com/strapi/assets/hair_color_03_81c0c8a3c8.jpg" --scale 2レスポンス：
{
"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. 結果を確認してダウンロードする
youcam status enhance <task_id>タスクの処理中は task_status が running です。数秒後にコマンドを再実行してください。完了すると：
{
"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 機能 を参照し、
youcam run <feature> --helpで各機能のオプションを確認してください。 - オプション、ファイル、JSON パラメータの仕組みは AI タスクの実行 を参照してください。
- 一部の機能は顔や体を先に検出します。前処理（顔と体の検出） を参照してください。
ユニットは YouCam API を利用するために消費する単位で、AI 機能ごとに消費数が異なります。API でも CLI でもユニットは "credit"（クレジット）と呼ばれるため、コマンド名は client credit と client credit-history になっています。公式 FAQ の 「ユニット」とはどのような意味で、どのように使われますか？ を参照してください。
youcam client credit # remaining units
youcam client credit-history # unit usage history大規模に実行する前に、各機能がいくつのユニットを消費するかを確認できます。
youcam client feature-costこれらのコマンドは --page_size と --starting_token <token> で結果をページ分けします：
credit-history:--page_size <1-30>、既定は 20。feature-cost:--page_size <1-20>、既定は 20。
注: 前処理 の検出タスクと プリセットテンプレートの取得 はユニットを消費しません。
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 をサポートしており、それぞれの使い方とオプションを表示します：
youcam run --help
youcam run face-swap --help結果は JSON で出力されます。リクエストが失敗すると、コマンドは終了コード 1 で終了します。
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 アップロード | ファイルオプションにローカルパスを渡すと自動実行されます（ファイルのアップロード を参照） |
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/youcamyoucam run image-to-image、run text-to-image、run image-to-video、run text-to-video/s2s/v2.0/task/colorize/color-correctyoucam run color-correctリクエストボディのプロパティは、対応する
runコマンドの--<property_name>オプションになります（ファイルのアップロード と JSON パラメータの渡し方 を参照）。page_sizeやstarting_tokenなどのクエリパラメータも--<param_name>オプションになります。
AI Hair Color Virtual Try-On を例にすると、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 コマンドに対応します：
youcam run hair-color --src_file <url-or-path> [--preset <value> | --pattern <json> --palettes <json>]
youcam status hair-color <task_id>プリセットの色を適用するには：
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 コマンドは次のリクエストボディを送信します：
{
"src_file_url": "https://plugins-media.makeupar.com/strapi/assets/hair_color_09_76a7a1081e.jpg",
"preset": "Honey Blonde"
}代わりにカスタム色を適用するには、pattern と palettes のオブジェクトを渡します：
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 リクエストボディは次の通りです：
{
"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 機能は run のサブコマンドです。オプションは機能ごとに異なります。各機能の入力は --help で確認してください。
youcam run <feature> [options]例えば AI Abs Filter を実行するには：
youcam run abs-shape --src_file "https://example.com/photo.jpg" --mode "Six-pack" --intensity 2タスクの実行は task_id を返します。それを使って ステータスを確認します。
- 前処理: 一部の機能は写真内の顔または体を先に検出するため、処理する人物を選べます。前処理（顔と体の検出） を参照してください。
- テンプレート: 一部の機能は
--template_idで既製のスタイルプリセットを受け付けます。プリセットテンプレートの取得 を参照してください。 - 検証: オプションの値は、送信前に API スキーマに照らしてチェックされます。値の集合が固定されているオプションは
--helpにその一覧が表示され、無効な値は許可されている選択肢とともに拒否されます。
画像または動画を受け取る全機能は、単一の --src_file オプションとして公開しています。API は相互排他な 2 つのフィールド——src_file_url（公開 URL）と src_file_id（アップロード済みファイルの ID）——を受け付けますが、CLI は渡された値に応じて正しい方を選びます：
- 公開されている URL は
src_file_urlとして送信されます。何もアップロードされません。youcam run enhance --src_file "https://example.com/photo.jpg" --scale 2 - ローカルファイルのパス は CLI がアップロードし、タスクは
src_file_idを使って送信されます：POST /s2s/v2.0/fileでファイルを登録し（名前、コンテンツタイプ、サイズ）、署名付きアップロード URL とfile_idを受け取ります。- ファイルのバイト列をその署名付き URL へ
PUTします。 run <feature>をsrc_file_idにそのfile_idを設定して呼び出します。
PowerShell や cmd では Windows のパスも使えます：youcam run enhance --src_file ./photo.jpg --scale 2youcam 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 つのフラグの後に複数の値をスペース区切りで受け取ります（カンマ区切りではありません）：
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 で確認できます。
以下に挙げる形式はいずれも同等です。お好みのものを使ってください：
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は不正のため拒否されます。
--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 / 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 つ）：
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 へ次のボディを送信します：
{
"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 も使えます：
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 パターン名の取得 を参照）。
不正な JSON や型の合わない値は、リクエスト送信前に拒否され、問題のあるフィールド名が示されます。例：Invalid value for --palettes: [{"color":123}] (0.color: Invalid input: expected string, received number)。
youcam status <feature> <task_id>
# or
youcam status <feature> --task_id <task_id>例：
youcam status abs-shape 1234567890abcdeftask_status が success（または error）になるまでポーリングしてください。その時点でレスポンスには結果（出力ファイルの URL など）が含まれます。前処理タスクの場合は youcam status pre-process <feature> <task_id> を使ってください。
前処理タスクはユニットを消費しません。ユニットを消費するのはメインタスクのみです。
以下の機能では、1 枚の写真に複数の人物が写っていることがあるため、処理する人物を選びます。youcam run pre-process <feature> は写真内の顔または体を検出し、リストとして返します。各検出結果はリスト中の位置によって番号が振られます：1 番目が 0、2 番目が 1、以下同です。
- 検出する：
youcam run pre-process <feature> --src_file <photo>がtask_idを返します。 - 検出結果を読む：
youcam status pre-process <feature> <task_id>で検出された顔または体の一覧を取得します。一覧の形は機能によって異なります。body-reshapeは画像サイズに対する相対値（0–1）のボックスを含むresults.result[]を返し、face-swapはピクセル単位のボックス[x1, y1, x2, y2]（左上と右下の角）を含むresults.faces[].bboxを返します。 - 同じ写真に対して機能を実行し、選んだ番号を下の表のオプションで渡します：
| 機能 | 検出された顔または体の番号を受け取るオプション |
|---|---|
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 番目に検出された顔をリフトします。実際の出力を伴う一連の実行は 使用例のワークフロー を参照してください。
一部の機能には既製のテンプレート（スタイルやルックのプリセット）が搭載されており、パラメータを自作する代わりに --template_id で参照できます。
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 パターン名の取得 を参照してください。
例：
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 のエフェクトは名前によって形状を選びます。例：チークなら "pattern":{"name":"1color1"}、リップカラーなら "shape":{"name":"plump"}。各エフェクトカテゴリーで有効な名前を取得できます：
youcam template makeup-vto <categories...>blush、bronzer、contour、eyebrows、eyeliner、eyeshadow、eyelashes、lipshape、lipliner、highlighter のうち 1 つ以上を指定します（同じ名を --category の後に並べることもできます）。最低 1 つは必須です。これらのカタログは公開されているため、取得にユニットは不要です。
youcam template makeup-vto blush lipshape結果はカテゴリーごとにまとまります。パターンの名前として各エントリの label を使用してください。colorNum（blush、eyeliner、eyeshadow のみ）は、そのパターンが必要とする palettes の数です：
{
"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 で終了します。
以下のいずれかを <feature> として run と status に指定してください。それぞれ API レファレンスのページにリンクしています。検出ステップがある機能は前処理（顔と体の検出）を、youcam template が使える機能はプリセットテンプレートの取得を参照してください。
- face-attr-analysis
- skin-analysis
- skin-tone-analysis
- fitzpatrick-scale-analyzer
- skin-simulation
- abs-shape
- aging
- body-reshape
- breast-shape
- face-lift
- face-reshape
- ai-smile
- teeth-whiten
- hair-density-detection
- hair-frizziness-detection
- hair-length-detection
- hair-type-detection
- hair-bang
- hair-color
- hair-curl
- hair-ext
- hair-transfer
- hair-vol
- beard-style
- enhance
- lighting
- colorize
- color-correct
- sod
- bg-blur
- bg-replace
- generative-fill
- obj-replace
- out-paint
- image-to-image
- text-to-image
- ai-avatar
- ai-studio
- headshot
- wmk-removal
- face-swap
各機能が受け取る正確なパラメータは youcam run <feature> --help で確認してください。
AI Body Reshape を最初から最後まで説明します。写真内の体を検出し、1 人を選び、補正し、結果を取得します。以下のリクエストボディとレスポンスボディは、このサンプル写真を使った実際の実行で取得したものです：
1. 検出（前処理）タスクを開始する
youcam run pre-process body-reshape \
--src_file "https://plugins-media.makeupar.com/strapi/assets/body_reshape_01_d10c50c97d.jpg"レスポンス：
{
"status": 200,
"data": {
"task_id": "CKPWaMO-olxd1ECr_3tTDXW5Gu_tQw0EKgN0-dU27zSyXhV8cJR2TzYLMhDqD"
}
}2. 検出された体を取得する
youcam status pre-process body-reshape CKPWaMO-olxd1ECr_3tTDXW5Gu_tQw0EKgN0-dU27zSyXhV8cJR2TzYLMhDqDレスポンス：
{
"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. 選んだ人物に対してメインタスクを実行する
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}'レスポンス：
{
"status": 200,
"data": {
"task_id": "ZV3WIzcB1rk7I5o8hMxKP5VdgIEpnHf7VOpsk1YC76tZy2Wur0lg4Bunb3KY-7Qa"
}
}4. 完了までメインタスクをポーリングする
youcam status body-reshape ZV3WIzcB1rk7I5o8hMxKP5VdgIEpnHf7VOpsk1YC76tZy2Wur0lg4Bunb3KY-7Qaタスクの実行中は task_status が running です。数秒ごとにコマンドを繰り返してください。成功すると（GET /s2s/v2.0/task/body-reshape/{task_id}）：
{
"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 ドキュメントの内容がそのままあてはまります。レート制限、エラーコード、ファイル保持期間は同じです。API 側の デバッグガイド も参照してください。
問題は 3 の地点で発生し得ます：
| 失敗する場所 | 終了コード | 標準出力 | 標準エラー出力 | 参照 |
|---|---|---|---|---|
| 送信前に CLI がコマンドを拒否する | 1 | 空 | エラーメッセージ | CLI のエラー |
| API がリクエストを拒否する | 1 | status、error、error_code を含む JSON | 空 | API リクエストのエラー |
| タスクは実行されたが失敗する | 0 | "task_status": "error"、data.error のコード、data.error_message の説明を含む JSON | 空 | タスクのエラー |
タスクが失敗しても終了コードは 0 になります。status リクエスト自体は成功しているためです。スクリプトは終了コードだけでなく data.task_status を確認する必要があります。
API のレート制限 はすべての 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 のエラーメッセージ | 考えられる原因 | 解決方法 |
|---|---|---|
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 パラメータの渡し方 を参照 |
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 がリクエストを拒否しました。CLI は API のレスポンスを標準出力に出力します。例：
{
"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 コンソール からキーをコピーし、youcam auth login を再実行します。使用例の行にある < > をキーに含めないでください |
429 | — | IP アドレスまたは API キーに対するリクエストが多すぎます | ペースを落とし、遅延を伸ばしながら再試行してください。レート制限 を参照 |
タスクは受け付けられましたが、AI エンジンが処理できませんでした。youcam status は "task_status": "error" を返し、コードは data.error、説明は data.error_message に入ります。コードは API の エラーコード ページで確認してください。一部の機能には追加のコードがあり、その機能の API レファレンスページの「ファイル仕様とエラー」に、サイズ・解像度・ポーズの制限とともに掲載されています。
結果の URL（例：results.url、ai-avatar の results.output[].url）は、タスク成功後 2 時間利用できます。期限切れの場合は youcam status <feature> <task_id> を再実行すると新しいリンクが取得できます。これはタスク作成後 30 日間有効です。結果は 30 日後に削除されるため、残しておきたいものはそれまでにダウンロードしてください。
youcam help
youcam help <command>
youcam <command> <subcommand> --help # e.g., youcam run pre-process --help