face-transform

顔の変換

AceDataCloud の Face API スイートを使用して、顔を分析・変換します。

初回セットアップ

1. clawhub install @acedatacloud/face-transform を実行して公式 Skill をインストールします。ClawHub の公開者が @acedatacloud であることを確認してください。
2. AceDataCloud → Applications にサインインし、General application を開いて、Face Transform のアクセス権、残高、現在の料金を確認します。API キーをコピーするか、Manage Keys → Create を選択して専用キーを作成します。Bearer を付けずにキーの値をコピーしてください。platform-... 形式の管理トークンはサービス API キーではありません。
3. Allowed APIs の制限を有効にする場合は、最初の例では /face/analyze を含めてください。ほかの顔関連の操作には、それぞれ個別のアクセス権が必要です。以下の高度なワークフローでは、追加のルートを呼び出す場合があります。
4. OpenClaw Gateway ホストで、ACEDATACLOUD_API_TOKEN=your_api_key_here を ~/.openclaw/.env に設定し、Gateway を再起動して新しいセッションを開始します。ターミナルから直接テストする場合は、そのシェルで export ACEDATACLOUD_API_TOKEN="your_api_key_here" を実行します。キーをプロンプトに含めたり、.env ファイルをコミットしたりしないでください。
5. 以下の クイックスタート を実行します。このワークフローからタスク ID が返された場合は、完了するまで同じタスクを照会してください。進行状況を確認するためだけに、同じ課金対象リクエストを再送信しないでください。

キーの設定、初回実行、トラブルシューティングの図解 · トークンの詳細

クイックスタート

curl -X POST https://api.acedata.cloud/face/analyze \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://cdn.acedata.cloud/lrbtcn.jpg"}'

利用可能な API

エンドポイント	用途	説明
POST /face/analyze	顔検出	顔の特徴点（1 顔あたり 90 個以上）を検出します
POST /face/beautify	美顔処理	美顔・装飾エフェクトを適用します
POST /face/change-age	年齢変換	顔を実際より老けて、または若く見せます
POST /face/change-gender	性別変換	顔の性別的特徴を変換します
POST /face/swap	顔の入れ替え	ある人物の顔を別の人物の顔に置き換えます
POST /face/cartoon	アニメ風スタイル	ポートレートをアニメ・漫画風のスタイルに変換します
POST /face/detect-live	生体検知	顔画像が実在する人物のものかどうかを検知します

ワークフロー

1. 顔分析

顔を検出し、1 顔あたり 90 個以上の特徴点を抽出します。

POST /face/analyze
{
  "image_url": "https://example.com/photo.jpg"
}

レスポンスには、詳細な特徴点が含まれます。nose、mouth、left_eye、right_eye、left_eyebrow、right_eyebrow、contour は、それぞれ {x, y} 座標の配列です。

2. 美顔処理

POST /face/beautify
{
  "image_url": "https://example.com/portrait.jpg"
}

3. 年齢変換

age_infos は必須です。各顔につき 1 つの項目を指定し、それぞれに変換後の age を設定します。

POST /face/change-age
{
  "image_url": "https://example.com/portrait.jpg",
  "age_infos": [{ "age": 60 }]
}

4. 性別変換

gender_infos は必須です。gender に 0 を指定すると男性の顔を女性に変換し、1 を指定するとその逆に変換します。

POST /face/change-gender
{
  "image_url": "https://example.com/portrait.jpg",
  "gender_infos": [{ "gender": 1 }]
}

5. 顔の入れ替え

ターゲット画像の顔を、ソース画像の顔に置き換えます。

POST /face/swap
{
  "source_image_url": "https://example.com/source-face.jpg",
  "target_image_url": "https://example.com/target-person.jpg"
}

6. アニメ風スタイル

POST /face/cartoon
{
  "image_url": "https://example.com/portrait.jpg"
}

7. 生体検知

POST /face/detect-live
{
  "image_url": "https://example.com/face-photo.jpg"
}

パラメーター

共通

パラメーター	必須	説明
image_url	必須（/face/swap を除くすべて）	ソース顔画像の URL

/face/change-age

パラメーター	必須	説明
age_infos	はい	{ "age": <number> } の配列。顔ごとに 1 つ指定します。省略すると 400 age_infos is required が返されます

/face/change-gender

パラメーター	必須	説明
gender_infos	はい	{ "gender": 0|1 } の配列。0 は男性から女性、1 は女性から男性への変換です。各項目では省略可能な face_rect も指定できます

/face/swap

パラメーター	必須	説明
source_image_url	はい	使用する顔の URL（置き換え元の顔）
target_image_url	はい	顔を合成する画像の URL
callback_url	いいえ	非同期配信用の Webhook URL
timeout	いいえ	最大待機時間（秒単位、デフォルト：120）

/face/beautify

パラメーター	必須	説明
image_url	はい	画像の URL
smoothing	いいえ	肌のスムージング 0～100（デフォルト：10）
whitening	いいえ	美白 0～100（デフォルト：30）
face_lifting	いいえ	顔の輪郭を細くする処理 0～100（デフォルト：70）
eye_enlarging	いいえ	目を大きくする処理 0～100（デフォルト：70）

/face/analyze

パラメーター	必須	説明
image_url	はい	画像の URL
mode	いいえ	0 = すべての顔（デフォルト）、1 = 最も大きい顔のみ
face_model_version	いいえ	アルゴリズムのバージョン（推奨：3.0）
need_rotate_detection	いいえ	0 = 無効（デフォルト）、1 = 有効

注意事項

• すべての顔 API は結果を同期的に返します。/face/swap ではオプションの callback_url パラメーターもサポートしており、指定すると、インラインで待機する代わりに Webhook 経由で結果を受け取れます。
• 顔分析では、検出した顔ごとに 90 個以上のキーポイントを返し、1 枚の画像内の複数の顔に対応しています。
• 顔の入れ替えでは、適用する顔を含む source_image_url と、その顔を適用する対象を含む target_image_url を使用します。
• すべての API は現在 Alpha 段階です。インターフェースは変更される可能性があります。
• 最良の結果を得るには、顔がはっきりと見える正面向きの画像を使用してください。
• 生体検知により、実際の人物を撮影した写真と、印刷物や画面を撮影した写真を区別できます。