# 服バーチャル試着 # 概要 AI Clothes で、服のバーチャル試着を作成します。 画像に衣装を重ね合わせて試着プレビューを生成します。 --- ## 統合ガイド * API プレイグラウンド API プレイグラウンドで AI Clothes のバーチャル試着機能をテストします。 API プレイグラウンドにアクセスするには: [https://yce.makeupar.com/api-console/en/api-playground/ai-clothes/](https://yce.makeupar.com/api-console/en/api-playground/ai-clothes/) --- * AI Clothes API 使用ガイド このガイドでは、画像のアップロード、参照衣装の準備、および AI Clothes API を使用したバーチャル試着タスクの作成方法について説明します。 --- * ステップ 1. File API を使用してファイルをアップロードする **File API** (`/s2s/v2.0/file`) を使用して、対象ユーザーの画像をアップロードします。 **画像要件:** * 高解像度の全身写真をアップロードしてください。 * 写真に全身がはっきりと映っていることを確認してください。 * 複数の人物や気が散るオブジェクトがある背景は避けてください。 **リクエスト例:** ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/file \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "files": [ { "content_type": "image/jpg", "file_name": "full_body_photo_01_3dbd1b6683.jpg", "file_size": 547541 } ] }' ``` --- * ステップ 2. File API レスポンスを取得する レスポンスには以下が含まれます: * AI タスク作成用の `file_id` 。 * 実際の画像ファイルをアップロードするための `requests.url` 。 **レスポンス例:** ```json { "status": 200, "data": { "files": [ { "content_type": "image/jpg", "file_name": "full_body_photo_01_3dbd1b6683.jpg", "file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud", "requests": [ { "method": "PUT", "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...", "headers": { "Content-Length": "547541", "Content-Type": "image/jpg" } } ] } ] } } ``` --- * ステップ 3. 提供された URL に画像をアップロードする File API レスポンスの `requests.url` を使用して画像をアップロードします: ```bash curl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \ --header 'Content-Type: image/jpg' \ --header 'Content-Length: 547541' \ --data-binary @'./full_body_photo_01_3dbd1b6683.jpg' ``` --- * ステップ 4. 参照衣装を準備する * 4.1 参照衣装画像をアップロードする 以下のいずれかの方法が可能です: * File API ( `/s2s/v2.0/file` ) を使用して衣装画像をアップロードする、または * 有効な画像 URL を提供する。 **サポートされる衣装画像:** * 服の商品画像。 * 衣装参照としての全身写真。 詳細な仕様については、**[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** を参照してください。 --- * ステップ 5. AI タスクを作成する **AI Task API** (`/s2s/v2.0/task/cloth-v4`) を使用して、バーチャル試着タスクを作成します。 **パラメータ:** * ユーザー画像用: `src_file_id` または `src_file_url` 。 * 衣装画像用: `ref_file_id` 、 `ref_file_url` 、または `template_id` 。 **リクエスト例:** ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/cloth-v4 \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/clothes_03_cccd5d4803.jpeg", "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/clothes_reference_full_body_01_5a000d999f.png", "garment_category": "full_body" }' ``` **レスポンス例:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` --- * ステップ 6. タスク結果をポーリングする タスク ID を使用してステータスを確認します: ```bash curl --request GET \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/cloth-v4/ \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' ``` --- * ステップ 7. 結果を取得する 成功したレスポンスには、結果画像のダウンロード URL が含まれます: ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` 無効な API キー エラー レスポンス: ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` --- ユースケース: ![](https://plugins-media.makeupar.com/smb/blog/post/2025-05-08/b80f4ae1-c905-4ec0-b491-e42c15e65575.gif) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/01%20ai%20clothes%20changer.jpg) ![](https://plugins-media.makeupar.com/smb/blog/post/2023-12-01/45f451aa-4b4f-466d-9da7-4538573c92af.jpg) 撮影方法のヒント: ![撮影方法のヒント](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI-Cloth-Guideline.png) ## ファイル仕様とエラー * サポートされる形式と寸法 | タイプ | サポートされる寸法 | サポートされるファイルサイズ | サポートされる形式 | | --- | --- | --- | --- | | 対象ユーザー画像 | 推奨: 1024×768、最小: 512×384、最大辺: 4096 px。 - 1 人のみ。 - 最適な結果を得るには、人物がフレームの少なくとも 80% を占めている必要があります。 - 画像には上半身のみを含め、胸から上を映してください。腹部は映す必要はありませんが、肩は見える必要があります。 - 顔全体がはっきりと見え、遮るものがない必要があります。 - 体は正面を向いて立っている状態である必要があります（座ったりしゃがんだりしていないこと）。 | < 10MB | jpg/png | | 服の参照画像 | 推奨: 1024×768、最小: 512×384、最大辺: 4096 px。 - 実写の服写真を参照として使用する場合   - 1 人のみである必要があります。   - 見える服の領域が、試着対象領域を完全にカバーしている必要があります。      - 例: 全身試着の場合、上半身のみの服画像は受け入れられません。      - 例: 下半身試着の場合、部分的なパンツ画像は受け入れられません。   - 服が激しく遮られていてはいけません（例: 長い髪や腕で覆われているなど）。   - 顔全体がはっきりと見え、遮るものがない必要があります。   - 体は正面を向いて立っている状態である必要があります（座ったりしゃがんだりしていないこと）。 - 商品画像を参照として使用する場合   - 単一の衣類の正面からの商品ショットである必要があります。   - 合成画像（例: 1 枚の写真にトップスとボトムスが含まれているなど）は使用しないでください。   - 下半身の場合、実際に着用された衣装のみがサポートされ、単独の商品画像はサポートされません。 | < 10MB | jpg/png | * エラーコード * エラーコード（前処理） | エラーコード | 説明 | | --- | --- | | exceed_max_filesize | SRC または REF 画像が大きすぎます。長辺は 4096 ピクセルを超えてはいけません。 | | error_below_min_image_size | SRC または REF 画像が小さすぎます。長辺は少なくとも 128 ピクセルである必要があります。 | | error_pose | アップロードされた人間の SRC 画像からポーズを検出できませんでした。 | | error_invalid_ref | REF 画像が無効です。例えば、空であるか、被写体が完全に見えていません。 | | error_apply_region_mismatch | SRC 画像内の適用領域が REF 画像と一致しないため、編集を適用できません。 | | error_invalid_src | ソース画像に下半身のみ、または足のみが映っている場合。 | * エラーコード（エンジン） | エラーコード | 説明 | | --- | --- | | invalid_parameter | - 無効な衣類カテゴリー。 - Style_id が inference_style_list に含まれていません。 - 無効な src_keys、dst_keys、または acts。 - 無効な ref_keys または template_ref_image。 - 必ずそのうち 1 つのみを提供してください。 | | error_download_image | SRC または REF 画像をダウンロードできませんでした。 | | exceed_max_filesize | SRC または REF 画像が大きすぎます。ファイルサイズは 10 MB を超えてはいけません。 | | error_nsfw_content_detected | 結果画像に潜在的な NSFW コンテンツが検出されました。 | | error_editing_failed | 結果画像がソース画像と類似しすぎているため、編集プロセスが失敗しました。 | | unknown_internal_error | - モデルの読み込みに失敗しました。 - 無効なスケジューラーアルゴリズムタイプ。 - エンジンが読み込まれていません。 - ファイルがアップロード結果に含まれていません。 | | error_multi_person | 「normal」または「strict」のマルチパーソンフィルター設定下で、ソース画像または参照画像に複数の人物が検出されました。 | * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | | --- | --- | | 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 | --- ## ユニット消費量 | AI 機能 | 消費ユニット | | --- | --- | | 服バーチャル試着 V2.0 | 2 | | 服バーチャル試着 V3.0 | 2 | --- 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_clothes.yaml) ## V4.0 - [POST /s2s/v2.0/task/cloth-v4](https://docs.perfectcorp.com/ja/reference/ai_clothes/v4.0/paths/~1s2s~1v2.0~1task~1cloth-v4/post.md): AI タスクは非同期です。機能ごとに Webhook がサポートされている場合は、Webhook による完了処理を優先します。Webhook エンドポイントを設定し、Webhook 署名を検証したうえで、`success` または `error` の通知が来たら、受け取った `task_id` を使ってタスクの結果を照会します。設定と検証の詳細は [Webhook 統合ガイド](/develop/ - [GET /s2s/v2.0/task/cloth-v4/{task_id}](https://docs.perfectcorp.com/ja/reference/ai_clothes/v4.0/paths/~1s2s~1v2.0~1task~1cloth-v4~1%7Btask_id%7D/get.md) ## V3.0 - [POST /s2s/v2.0/task/cloth-v3](https://docs.perfectcorp.com/ja/reference/ai_clothes/v3.0/paths/~1s2s~1v2.0~1task~1cloth-v3/post.md): AI タスクは非同期です。機能ごとに Webhook がサポートされている場合は、Webhook による完了処理を優先します。Webhook エンドポイントを設定し、Webhook 署名を検証したうえで、`success` または `error` の通知が来たら、受け取った `task_id` を使ってタスクの結果を照会します。設定と検証の詳細は [Webhook 統合ガイド](/develop/ - [GET /s2s/v2.0/task/cloth-v3/{task_id}](https://docs.perfectcorp.com/ja/reference/ai_clothes/v3.0/paths/~1s2s~1v2.0~1task~1cloth-v3~1%7Btask_id%7D/get.md) ## V2.0 - [GET /s2s/v2.0/task/template/cloth](https://docs.perfectcorp.com/ja/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1template~1cloth/get.md) - [POST /s2s/v2.0/task/cloth](https://docs.perfectcorp.com/ja/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1cloth/post.md): このエンドポイントは、服バーチャル試着プロセスを開始します。テンプレート ID を使用するか、参照画像（ソースファイルと参照ファイル）を提供できます。タスクは非同期で処理され、このレスポンスで返される task_id を使用してステータスを確認できます。 - [GET /s2s/v2.0/task/cloth/{task_id}](https://docs.perfectcorp.com/ja/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1cloth~1%7Btask_id%7D/get.md)