# AI 顔交換 # 概要 AI 顔交換では、写真内の顔を交換します。1 つまたは複数の顔の交換に対応しています。 ## 統合ガイド * AI 顔交換の実装方法 * ステップ 1: ソース画像と参照画像のアップロード 1. API からアップロード URL をリクエストします: ``` POST https://yce-api-01.makeupar.com/s2s/v2.0/file Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` ボディ: ```json { "files": [ { "file_name": "target.jpg", "file_size": 123456, "content_type": "image/jpeg" } ] } ``` 1. レスポンスには、事前署名付きの **アップロード URL** と `file_id` が含まれます。 2. 指定された URL に対して HTTP PUT リクエストでファイルをアップロードします。 3. 後で使用するために `file_id` を保存します。**ターゲット**画像と**参照**画像の両方に対してこの手順を繰り返します。 4. 実際のファイルを **アップロード URL** にアップロードします。 --- * ステップ 2: ソース画像と参照画像の前処理（顔検出） 1. 前処理タスクを作成します: ``` POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` ボディ: ```json { "request_id": 1, "payload": { "file_sets": { "src_ids": ["TARGET_FILE_ID"] }, "actions": [ { "id": 0 } ] } } ``` 1. API は `task_id` を返します。 2. タスクのステータスを次の URL でポーリングします: ``` GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process?task_id=TASK_ID ``` 1. 完了すると、バウンディングボックス付きの検出された顔のリストを受け取ります。 --- * ステップ 3: 顔交換タスクの実行 1. どの参照画像が各ソース画像を置き換えるかを定義します `face_mapping` 配列は、 **ソース画像** 内の顔が **参照画像** 内の顔によってどのように置き換えられるかを定義します。これは、ソース内で検出された顔を特定の参照画像に接続するリンクリストとして機能します。 * 構造 配列内の各要素は、2 つのプロパティを含むオブジェクトです: | パラメータ | 型 | 説明 | | --- | --- | --- | | `position` | `integer` | **ソース画像**内で検出された顔のインデックス（例: 0, 1, 2）。 | | `index` | `integer` | 交換対象となる**参照画像リスト**内の顔画像のインデックス。 | * ロジックルール 1. **インデックスマッピング:** `index` は、参照リストに提供された画像の順序に直接対応します。 * `0` : 1 番目の参照画像。 * `1` : 2 番目の参照画像。 2. **交換のスキップ:** ソース内で検出された特定の顔の交換をスキップするには、`index` と `position` の両方を `-1` に設定します。 3. **配列の順序:** 配列内のオブジェクトの順序は、`position` に基づいて一致させる必要があります。 * 使用例 **シナリオ:** * **参照リスト:** 2 枚の画像を提供（画像 A、画像 B）。 * **ソース画像:** 3 つの顔が検出される（顔 0、顔 1、顔 2）。 **目標:** * **顔 0** （ソース）を **画像 1** （参照）と交換する。 * **顔 1** （ソース）の交換をスキップする。 * **顔 2** （ソース）を **画像 0** （参照）と交換する。 **設定:** ```json "face_mapping": [ { "index": 1, // Use the second reference image "position": 0 // Apply to the first detected face in source }, { "index": -1, // Skip swapping "position": -1 // Skip swapping }, { "index": 0, // Use the first reference image "position": 2 // Apply to the third detected face in source } ] ``` 1. メインタスクリクエストを送信します: ``` POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` ボディ: ```json { "request_id": 2, "payload": { "file_sets": { "src_ids": ["TARGET_FILE_ID"], "ref_ids": ["REFERENCE_FILE_ID"] }, "actions": [ { "id": 0, "params": { "face_mapping": [ { "index": 0, "position": 0 }, { "index": -1, "position": -1 } ] } } ] } } ``` 1. レスポンスには `task_id` が返されます。 --- * ステップ 4: タスクステータスのポーリングと結果の取得 許可されたポーリングウィンドウ内で、一定の間隔でタスクステータスを照会するタイミングループを実装する必要があります。 1. 次の URL でポーリングします: ``` GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap?task_id=TASK_ID ``` 1. `status` が `success` になると、レスポンスには生成された画像の URL が含まれます。 2. その URL から画像をダウンロードまたは表示します。 --- * ステップ 5: プラットフォームへの統合 * **Web フロントエンド** では、fetch または Axios を使用して JavaScript で直接実装できます。 * **バックエンド** （Node.js、Python、Java、PHP など）では、標準的な HTTP ライブラリを使用して同じエンドポイントを使用できます。 * タスクは非同期で実行されるため、リトライとエラーハンドリングを実装してください。 --- * デバッグガイド 1. **Invalid TaskId エラー** **理由:** タイムアウトしたタスクのステータスを確認しようとすると、InvalidTaskId エラーが発生します。したがって、AI タスクが開始されたら、ステータスが success または error に変わるまで、polling_interval 内でステータスをポーリングする必要があります。 **解決策:** タスクが無効になるのを避けるために、許可されたポーリングウィンドウ内で一定の間隔でタスクステータスを照会するタイミングループを実装する必要があります。 2. **ソース画像で一部の顔が検出されない理由** **理由:** 顔がはっきりと見えており、覆われたり遮られたりしておらず、画像内で十分に大きい必要があります。 **解決策:** 顔が大きく写っており、覆いや遮りがなくはっきりと見える写真を撮影してみてください。 --- ## 入力と出力 * 実際の例: 複数顔交換サンプル: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_04_d4b747a41d.jpg) 単一顔交換サンプル: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_05_8e68faff2c.jpg) * 撮影方法の提案: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png) ## ファイル仕様とエラー * 対応フォーマットと寸法 | AI 機能 | 対応寸法 | 対応ファイルサイズ | 対応フォーマット | | --- | --- | --- | --- | | AI 顔交換 | 入力と出力: 長辺が 4096 ピクセル以下 | < 10MB | jpg/jpeg/png | * エラーコード | エラーコード | 説明 | | --- | --- | | exceed_max_filesize | 入力ファイルサイズが最大制限を超えています | | invalid_parameter | パラメータ値が無効です | | error_download_image | ソース画像のダウンロード中にエラーが発生しました | | error_download_mask | マスク画像のダウンロード中にエラーが発生しました | | error_decode_image | ソース画像のデコード中にエラーが発生しました | | error_decode_mask | マスク画像のデコード中にエラーが発生しました | | error_download_video | ソース動画のダウンロード中にエラーが発生しました | | error_decode_video | ソース動画のデコード中にエラーが発生しました | | error_nsfw_content_detected | ソース画像で NSFW コンテンツが検出されました | | error_no_face | ソース画像で顔が検出されませんでした | | error_pose | ソース画像でポーズの検出に失敗しました | | error_face_parsing | ソース画像での顔解析に失敗しました | | error_inference | 推論パイプラインでエラーが発生しました | | exceed_nsfw_retry_limits | NSFW 画像の生成を避けるためのリトライ制限を超えました | | error_upload | 結果画像のアップロード中にエラーが発生しました | | error_multiple_people | 人物の数が最大制限を超えています | | error_no_shoulder | ソース画像で肩が見えません | | error_large_face_angle | アップロード画像の顔の角度が大きすぎます | | error_unsupport_ratio | 入力画像のアスペクト比はサポートされていません | | unknown_internal_error | その他の内部エラー | --- ## ユニット消費量 | 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 - [AI 顔交換](https://docs.perfectcorp.com/_bundle/@l10n/ja/reference/ai_face_swap.yaml) ## V1.0 - [POST /s2s/v2.0/task/face-swap/pre-process](https://docs.perfectcorp.com/ja/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process/post.md): ソース画像に複数の有効なターゲットが含まれる可能性がある場合、またはエフェクトを適用する検出ターゲットを明示的に選びたい場合は、前処理タスクを使います。単一ターゲットの画像では、機能がデフォルトの `index` 値をサポートしているため、手動でのターゲット選択が不要な場合は前処理をスキップできます。 前処理タスクは、ソース画像内の候補ターゲットを検出し、その座標を `data.results.r - [GET /s2s/v2.0/task/face-swap/pre-process/{task_id}](https://docs.perfectcorp.com/ja/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process~1%7Btask_id%7D/get.md) - [POST /s2s/v2.0/task/face-swap](https://docs.perfectcorp.com/ja/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap/post.md): AI タスクは非同期です。機能ごとに Webhook がサポートされている場合は、Webhook による完了処理を優先します。Webhook エンドポイントを設定し、Webhook 署名を検証したうえで、`success` または `error` の通知が来たら、受け取った `task_id` を使ってタスクの結果を照会します。設定と検証の詳細は [Webhook 統合ガイド](/develop/ - [GET /s2s/v2.0/task/face-swap/{task_id}](https://docs.perfectcorp.com/ja/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1%7Btask_id%7D/get.md)