# 顔パーツ補正 # 概要 AI 顔パーツ補正 API では、目、鼻、唇、顎、顔全体のパーツを補正します。 美容治療ワークフローのビフォーアフタープレビューに使用します。 * 鼻形成術（隆鼻術） オンライン鼻形成シミュレーターで、鼻梁、リフト、小鼻などをシミュレーションします。 * 顎フィラー 顎フィラーの効果をプレビューします。顎の長さと顎の形を調整します。 * 唇フィラー 唇フィラーの効果をプレビューします。唇のボリュームと形を調整します。 * 眉リフト手術 眉リフトの結果をプレビューします。 ## 統合ガイド このガイドでは、以下を説明します： AI 顔パーツ補正 API のワークフロー： **エンドポイント:** `/s2s/v2.0/file` **認証が必要:** `Authorization: Bearer YOUR_API_KEY` **ワークフローの手順:** 1. **画像アップロードの準備:** - アップロード用のセルフィー画像を準備します。 - File API `/s2s/v2.0/file` を呼び出し、アップロード URL と関連する `file_id` を取得します。 - 提供されたアップロード URL を使用してセルフィー画像をアップロードします。 2. **複数顔の場合のオプションの前処理:** - 画像内に複数の顔がある場合、セルフィー画像を前処理します。 3. **顔パーツ補正効果の設定:** - まず、目、顔、唇、または鼻に適した顔パーツ補正パラメータを選択します。 4. **AI タスクの開始とタスク ID の取得:** - 選択した効果設定とともに `file_id` を HTTP POST リクエストで `/s2s/v2.0/task/face-reshape` に送信します。 - このやり取りを識別する一意のタスク ID をレスポンスで待ちます。 5. **タスクステータスのポーリング（継続的な確認）:** - 取得した `task_id` を使用し、HTTP GET リクエスト（例： `GET /s2s/v2.0/task/face-reshape/${task_id}` ）で定期的にタスクステータスをポーリングします。 - 以下を継続的に監視します： - `Task_status = "success"` （処理完了）。 - `Task_status = "error"` （該当する場合、解決または再試行）。 - ステータスが success に遷移したら、ワークフローを適切に更新します。 --- * API プレイグラウンド API プレイグラウンドで API を対話的にテストします： **API プレイグラウンド:** [http://yce.makeupar.com/api-console/en/api-playground/ai-face-reshape/](http://yce.makeupar.com/api-console/en/api-playground/ai-face-reshape/) --- * 認証 - **Bearer トークン** を使用して、リクエストヘッダーに API キーを含めます： ``` Authorization: Bearer YOUR_API_KEY ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. 1. 画像のアップロード ファイルをサーバーに直接アップロードするか、AI タスクペイロードに有効な画像 URL を指定します。 * アップロードエンドポイント ``` POST /s2s/v2.0/file ``` すでに公開画像 URL がある場合は、この手順をスキップできます。 --- 1. 効果テンプレートの準備 * 前処理 ピクセル座標で検出されたバウンディングボックスを出力します。結果のインデックスを使用して、後で顔パーツ補正 AI タスクを作成します。 ``` { "timed": number, "result": [ { "left": number, "top": number, "width": number, "height": number } ] } ``` * 効果テンプレート JSON スキーマ ``` { "version": "1.0", "index": 0, "features": {}, "global": { "skin_smooth_strength": 50, "skin_smooth_color_intensity": 50, }, } ``` index: 前処理で検出された顔のインデックス。省略可、初期値 0。 features: 少なくとも 1 つの非ゼロの顔パーツ補正パラメータが必要。すべてゼロにはできません。 skin_smooth_strength: 0~100 skin_smooth_color_intensity: 0~100 * 効果フォーマット - 顔 初期範囲: -100~100 頬骨と顎の範囲: 0~100 すべての機能値が同時にゼロであってはなりません。少なくとも 1 つの機能値は非ゼロである必要があります ``` { "cheekbones": 0, "jaw": 0, "face_reshape_left": 0, "face_reshape_right": 0, "face_width": 0, "chin_reshape_left": 0, "chin_reshape_right": 0, "chin_length": 0, } ``` - 目 初期範囲: -100~100 すべての機能値が同時にゼロであってはなりません。少なくとも 1 つの機能値は非ゼロである必要があります ``` { "eye_size_left": 0, "eye_size_right": 0, "eye_distance": 0, "eye_angle": 0, "eye_height": 0, "eye_width": 0, } ``` - 鼻 初期範囲: -100~100 すべての機能値が同時にゼロであってはなりません。少なくとも 1 つの機能値は非ゼロである必要があります ``` { "nose_bridge_width": 0, "nose_lift": 0, "nose_size": 0, "nose_tip": 0, "nose_tip_width": 0, "nose_wing": 0 } ``` - 唇 初期範囲: -100~100 すべての機能値が同時にゼロであってはなりません。少なくとも 1 つの機能値は非ゼロである必要があります ``` { "lip_size": 0, "lip_width": 0, "lip_peak": 0, "lip_height_top": 0, "lip_height_bottom": 0, } ``` * ペイロードの例（送信可能） ``` { "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/face_reshape_01_85c8ffc055.jpg", "version": "1.0", "source": "yco", "features": { "eye_size_left": 80, "eye_size_right": 80, "eye_width": 0, "eye_height": 0, "eye_distance": 0, "eye_angle": 0, "face_reshape_left": 0, "face_reshape_right": 0, "chin_reshape_left": 20, "chin_reshape_right": 20, "chin_length": 0, "face_width": -30, "cheekbones": 0, "jaw": 0, "lip_size": 10, "lip_width": 40, "lip_height_top": 10, "lip_height_bottom": 10, "lip_peak": -10, "nose_size": 30, "nose_lift": -20, "nose_bridge_width": 10, "nose_tip": -10, "nose_wing": 30, "nose_tip_width": 30 }, "global": { "skin_smooth_strength": 50, "skin_smooth_color_intensity": 50 } } ``` 2. 顔パーツ補正 AI タスクの作成と結果のポーリング 画像と完全な効果ペイロードが用意できたら、タスクを作成します。API はリクエストを非同期で処理します。タスクステータスが `success` または `error` に達するまでポーリングする必要があります。 * タスク作成エンドポイント ``` POST /s2s/v2.0/task/face-reshape ``` * ポーリングエンドポイント ``` GET /s2s/v2.0/task/face-reshape/{task_id} ``` --- ## ファイル仕様とエラー * AI 顔パーツ補正仕様 **サポートされるセルフィービュー** 画像の幅と高さの 1/20 より大きい顔の幅と高さを持つセルフィー。 ピッチ、ヨー、ロールの顔角度は 30 度未満。 ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_face_reshape_01_85c8ffc055.jpg) **顔カスタマイズパラメータガイド** | カテゴリ | パラメータ | 機能 | 最小 (-100 / 0) | 最大 (100) | | --- | --- | --- | --- | --- | | 目 | サイズ (左/右) | 各目の全体的なサイズをスケーリング | 小さい | 大きい | | 目 | 幅 | 水平方向の範囲を調整 | 狭い | 広い | | 目 | 高さ | 垂直方向の範囲を調整 | 狭い / 平たい | 丸い / 高い | | 目 | 間隔 | 目と目の間の間隔を調整 | 近い | 遠い | | 目 | 角度 | 回転の傾きを調整 | 内側傾き | 外側傾き | | 顔 | サイズ (左/右) | 顔の各側のサイズをスケーリング | 小さい | 大きい | | 顔 | 顎の形 (左/右) | 顎の輪郭の幅を調整 | 狭い | 広い | | 顔 | 顎の長さ | 顎の垂直方向の長さを調整 | 短い | 長い | | 顔 | 幅 | 顔全体の幅を調整 | 狭い | 広い | | 顔 | 頬骨 | 頬骨の突出を調整 | 元 (0) | 引き締める | | 顔 | 顎 | 顎ラインの突出を調整 | 元 (0) | 引き締める | | 唇 | サイズ | 唇全体のボリュームをスケーリング | 小さい | 大きい | | 唇 | 幅 | 水平方向の範囲を調整 | 狭い | 広い | | 唇 | 上唇の高さ | 上唇の厚さを調整 | 薄い | 厚い | | 唇 | 下唇の高さ | 下唇の厚さを調整 | 薄い | 厚い | | 唇 | 山形 | キューピッドボウの鋭さを調整 | なめらか | 明確 | | 鼻 | サイズ | 鼻全体のサイズをスケーリング | 小さい | 大きい | | 鼻 | リフト | 垂直方向の位置を調整 | 低い | 高い | | 鼻 | 鼻梁 | 鼻梁の幅を調整 | 狭い | 広い | | 鼻 | 鼻尖 | 鼻尖の垂直角度を調整 | 上向き | 下向き | | 鼻 | 小鼻 | 鼻孔の幅を調整 | 狭い | 広い | | 鼻 | 幅 | 鼻尖の幅を調整 | 狭い | 広い | **注意:** *“左”と“右”はキャラクターの視点であり、視聴者の画面の側ではありません。* --- * サポートされる形式と寸法 | AI 機能 | サポートされる寸法 | サポートされるファイルサイズ | サポートされる形式 | | --- | --- | --- | --- | | AI 顔パーツ補正 | 長辺 <= 4096 | < 10MB | jpg/jpeg/png | * エラーコード | エラーコード | 説明 | | --- | --- | | RUNTIME_ERROR | 顔パーツ補正の実行中に予期しないエラーが発生しました | | PHOTO_DETECTION_FAIL | ユーザー写真を正しく処理できませんでした。例えば、手が検出されませんでした | | OBJECT_DETECTION_FAIL | オブジェクト写真を正しく処理できませんでした。例えば、製品が検出されませんでした | | PHOTO_CHECK_INVALID | ユーザー写真のポーズまたはサイズが無効です | | INPUT_ERROR | 入力ファイル形式が正しくありません | | INPUT_MAIN_IMAGE_EMPTY | ユーザー画像が必要です | * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | | --- | --- | | cURL | - bash >= 3.2 - curl >= 7.58 (モダンな TLS/HTTP サポート) - jq >= 1.6 (堅牢な JSON 解析) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80 - Firefox >= 74 - Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性のため), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## JS カメラキット --- ## ユニット消費量 | AI 機能 | 消費ユニット | | --- | --- | | AI 顔パーツ補正 V1.0 | 1 | --- License: Privacy policy ## Servers ``` https://yce-api-01.makeupar.com ``` ## Security ### BearerAuthenticationV2 標準の 'Bearer authentication' を使用します。ヘッダーに 'API Key' を設定してください: `Authorization:Bearer YOUR_API_KEY`。'Bearer' と 'YOUR_API_KEY' の間にスペース ' ' があることに注意してください。 Type: http Scheme: bearer ## Download OpenAPI description - [顔パーツ補正](https://docs.perfectcorp.com/_bundle/@l10n/ja/reference/ai_face_reshape.yaml) ## V1.0 - [POST /s2s/v2.0/task/face-reshape/pre-process](https://docs.perfectcorp.com/ja/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1pre-process/post.md): ソース画像に複数の有効なターゲットが含まれる可能性がある場合、またはエフェクトを適用する検出ターゲットを明示的に選びたい場合は、前処理タスクを使います。単一ターゲットの画像では、機能がデフォルトの `index` 値をサポートしているため、手動でのターゲット選択が不要な場合は前処理をスキップできます。 前処理タスクは、ソース画像内の候補ターゲットを検出し、その座標を `data.results.r - [GET /s2s/v2.0/task/face-reshape/pre-process/{task_id}](https://docs.perfectcorp.com/ja/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1pre-process~1%7Btask_id%7D/get.md): ソース画像に複数の有効なターゲットが含まれる可能性がある場合、またはエフェクトを適用する検出ターゲットを明示的に選びたい場合は、前処理タスクを使います。単一ターゲットの画像では、機能がデフォルトの `index` 値をサポートしているため、手動でのターゲット選択が不要な場合は前処理をスキップできます。 前処理タスクは、ソース画像内の候補ターゲットを検出し、その座標を `data.results.r - [POST /s2s/v2.0/task/face-reshape](https://docs.perfectcorp.com/ja/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape/post.md): AI タスクは非同期です。機能ごとに Webhook がサポートされている場合は、Webhook による完了処理を優先します。Webhook エンドポイントを設定し、Webhook 署名を検証したうえで、`success` または `error` の通知が来たら、受け取った `task_id` を使ってタスクの結果を照会します。設定と検証の詳細は [Webhook 統合ガイド](/develop/ - [GET /s2s/v2.0/task/face-reshape/{task_id}](https://docs.perfectcorp.com/ja/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1%7Btask_id%7D/get.md)