{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-@l10n/ja/reference/ai_retake.yaml","sidebar":"sidebar-@l10n/ja/reference/sidebars.yaml"},"props":{"definitionId":"@l10n/ja/reference/ai_retake.yaml","settings":{"baseUrlPath":"/ja/reference/ai_retake"},"disableAutoScroll":true,"seo":{"title":"AI リテイク","description":"YouCam API documentation by Perfect Corp. Learn how to use Skin analysis API, Virtual try-on API, Image editing API, and Video generative AI APIs.","siteUrl":"https://docs.perfectcorp.com","keywords":"AI Skin Analysis, AI Clothes, AI Hairstyle, AI Outfits","image":"/assets/favicon.cd6fa4d833b2a573b3c6dae68386b293da205b203402cb0c97b80bd2acc07ea2.8351e24f.png"},"dynamicMarkdocComponents":[],"metadata":{"type":"openapi","title":"AI リテイク","version":"","description":"# 概要\nシーンはそのままに、顔だけを作り替える。AI Retake なら、集合写真を 1 人ずつ作り替えることができます。面白い顔の写真を作る場合も、プロ仕様のツールが必要な場合も、本 API が対応します。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-01-14/3d504686-8057-418e-a0cb-eba3d47ea42c.jpg)\n\n## 統合ガイド\n* AI Retake の実装方法\n\n   * ステップ 1: 元画像と参照画像をアップロードする\n\n      1. API にアップロード URL をリクエストします：\n\n        ```\n        POST https://yce-api-01.makeupar.com/s2s/v2.0/file\n        Authorization: Bearer YOUR_API_KEY\n        Content-Type: application/json\n        ```\n\n        Body:\n\n        ```json\n        {\n            \"files\": [\n            {\n                \"file_name\": \"target.jpg\",\n                \"file_size\": 123456,\n                \"content_type\": \"image/jpeg\"\n            }\n            ]\n        }\n        ```\n        1. レスポンスには、署名付きの **アップロード URL** と `file_id` が含まれます。\n        2. 指定された URL に対して HTTP PUT リクエストでファイルをアップロードします。\n        3. あとで使うため `file_id` を保存します。**対象** 画像と **参照** 画像の両方についてこの手順を繰り返します。\n\n      2. **アップロード URL** に実際のファイルをアップロードします。\n\n---\n\n   * ステップ 2: 元画像と参照画像を前処理する（顔検出）\n\n        1. 前処理タスクを作成します：\n\n        ```\n        POST https://yce-api-01.makeupar.com/s2s/v2.0/task/retake/pre-process\n        Authorization: Bearer YOUR_API_KEY\n        Content-Type: application/json\n        ```\n\n        Body:\n\n        ```json\n        {\n            \"request_id\": 1,\n            \"payload\": {\n            \"file_sets\": {\n                \"src_ids\": [\"TARGET_FILE_ID\"]\n            },\n            \"actions\": [\n                { \"id\": 0 }\n            ]\n            }\n        }\n        ```\n        1. API が `task_id` を返します。\n        2. 次の URL でタスクステータスをポーリングします：\n\n        ```\n        GET https://yce-api-01.makeupar.com/s2s/v2.0/task/retake/pre-process?task_id=TASK_ID\n        ```\n        1. 完了すると、検出された顔のリストと、それぞれのバウンディングボックスが返されます。\n\n---\n\n   * ステップ 3: AI Retake タスクを実行する\n        1. どの参照画像で元画像の顔を置き換えるかを定義する\n        `face_mapping` 配列は、**元画像**（Source Image）の顔を **参照画像**（Reference Images）の顔でどのように置き換えるかを定義します。元画像で検出された顔と、特定の参照画像とを結ぶリンクリストとして機能します。\n\n        * 構造\n\n            配列の各要素は、次の 2 つのプロパティを含むオブジェクトです：\n\n            | パラメータ | 型 | 説明 |\n            | :--- | :--- | :--- |\n            | `position` | `integer` | **元画像** で検出された顔のインデックス（例: 0, 1, 2）。 |\n            | `index` | `integer` | 置き換えに使う **参照画像リスト** 内の顔画像のインデックス。 |\n\n                * ロジックのルール\n            1.  **インデックスの対応:** `index` は、参照リストに指定した画像の並び順に直接対応します。\n                *   `0`: 1 番目の参照画像。\n                *   `1`: 2 番目の参照画像。\n            2.  **置き換えをスキップする:** 元画像で検出された特定の顔の置き換えをスキップするには、`index` と `position` の両方を `-1` に設定します。\n            3.  **配列の並び順:** 配列内のオブジェクトの並び順は、`position` に応じた順にします。\n\n                * 利用例\n\n            **シナリオ:**\n            *   **参照リスト:** 画像を 2 枚指定（画像 A、画像 B）。\n            *   **元画像:** 顔が 3 つ検出される（顔 0、顔 1、顔 2）。\n\n            **目的:**\n            *   **元画像の顔 0** を **参照画像 1** で置き換える。\n            *   **元画像の顔 1** は置き換えをスキップする。\n            *   **元画像の顔 2** を **参照画像 0** で置き換える。\n\n            **設定:**\n\n            ```json\n            \"face_mapping\": [\n                {\n                    \"index\": 1,  // Use the second reference image\n                    \"position\": 0 // Apply to the first detected face in source\n                },\n                {\n                    \"index\": -1, // Skip replacing\n                    \"position\": -1 // Skip replacing\n                },\n                {\n                    \"index\": 0,  // Use the first reference image\n                    \"position\": 2 // Apply to the third detected face in source\n                }\n            ]\n            ```\n\n        1. メインタスクのリクエストを送信します：\n\n        ```\n        POST https://yce-api-01.makeupar.com/s2s/v2.0/task/retake\n        Authorization: Bearer YOUR_API_KEY\n        Content-Type: application/json\n        ```\n\n        Body:\n\n        ```json\n        {\n            \"request_id\": 2,\n            \"payload\": {\n            \"file_sets\": {\n                \"src_ids\": [\"TARGET_FILE_ID\"],\n                \"ref_ids\": [\"REFERENCE_FILE_ID\"]\n            },\n            \"actions\": [\n                {\n                \"id\": 0,\n                \"params\": {\n                    \"face_mapping\": [\n                    { \"index\": 0, \"position\": 0 },\n                    { \"index\": -1, \"position\": -1 }\n                    ]\n                }\n                }\n            ]\n            }\n        }\n        ```\n        1. レスポンスには `task_id` が返されます。\n\n---\n\n   * ステップ 4: タスクステータスをポーリングして結果を取得する\n         ポーリングが許可された時間枠内で、一定間隔ごとにタスクステータスを問い合わせるタイムドループを実装する必要があります。\n         1. 次の URL でポーリングします：\n\n        ```\n        GET https://yce-api-01.makeupar.com/s2s/v2.0/task/retake?task_id=TASK_ID\n        ```\n        2. `status` が `success` になると、レスポンスに生成画像の URL が含まれます。\n        3. その URL から画像をダウンロード、または表示します。\n\n---\n\n   * ステップ 5: ご自身のプラットフォームに統合する\n\n        * **Web フロントエンド** では、fetch や Axios を使って JavaScript で直接実装できます。\n        * **バックエンド**（Node.js、Python、Java、PHP など）では、同じエンドポイントを標準の HTTP ライブラリで利用できます。\n        * タスクは非同期で実行されるため、リトライとエラーハンドリングを実装してください。\n\n---\n\n     * デバッグガイド\n\n         1. **元画像の一部の顔が検出されないのはなぜですか**\n             </br>**理由:** 顔がはっきり写っており、覆われたり遮られたりしておらず、画像内で十分に大きいサイズである必要があります\n             </br>**解決方法:** 顔を大きく写し、覆いや遮るものなくはっきり確認できる写真で撮り直してください\n\n---\n\n## 入力と出力\n\n* 実際の例：\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-01-14/9aeab2bb-28aa-48f5-ab86-2edd897ad908.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-07-02/webp_0196a9d4-1430-4121-9680-5e81b58b66ac.webp)\n\n\n## 対応ファイル仕様とエラー\n* サポートされている形式と寸法\n\n| AI 機能 | サポートされている寸法 | サポートされているファイルサイズ | サポートされている形式 |\n| ---- | ---- | ---- | ---- |\n| AI Retake | 入力・出力ともに長辺 4096 ピクセル以下 | < 10MB | jpg/jpeg/png |\n\n\n* エラーコード\n\n| エラーコード | 説明 |\n| ------------------ | ----------- |\n| exceed_max_filesize | 入力ファイルサイズが上限を越えています |\n| invalid_parameter | パラメータの値が無効です |\n| error_download_image | 元画像のダウンロード中にエラーが発生しました |\n| error_download_mask | マスク画像のダウンロード中にエラーが発生しました |\n| error_decode_image | 元画像のデコード中にエラーが発生しました |\n| error_decode_mask | マスク画像のデコード中にエラーが発生しました |\n| error_download_video | 元動画のダウンロード中にエラーが発生しました |\n| error_decode_video | 元動画のデコード中にエラーが発生しました |\n| error_nsfw_content_detected | 元画像に NSFW コンテンツが検出されました |\n| error_no_face | 元画像で顔が検出されませんでした |\n| error_pose | 元画像でポーズの検出に失敗しました |\n| error_face_parsing | 元画像の顔解析に失敗しました |\n| error_inference | 推論パイプラインでエラーが発生しました |\n| exceed_nsfw_retry_limits | NSFW 画像の生成を避けるためのリトライ上限を越えました |\n| error_upload | 結果画像のアップロード中にエラーが発生しました |\n| error_multiple_people | 人物の数が上限を越えています |\n| error_no_shoulder | 元画像に肩が写っていません |\n| error_large_face_angle | アップロードされた画像の顔の角度が大きすぎます |\n| error_unsupport_ratio | 入力画像のアスペクト比はサポートされていません |\n| unknown_internal_error | その他の内部エラー |\n\n---\n\n## ユニット消費量\n\n| AI 機能 | 消費ユニット |\n|---|---|\n| AI Retake V2.0 | 1 |\n\n---\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"docs.perfectcorp.com","port":4000,"ipAddress":"216.73.216.105"},"lang":"ja","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"master"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/ja/reference/ai_retake","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}