# 服バーチャル試着
# 概要
AI Clothes で、服のバーチャル試着を作成します。
画像に衣装を重ね合わせて試着プレビューを生成します。
---
## 統合ガイド
* API プレイグラウンド
API プレイグラウンドで AI Clothes のバーチャル試着機能をテストします。
API プレイグラウンドにアクセスするには:
---
* 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"
}
```
---
ユースケース:
撮影方法のヒント:
## ファイル仕様とエラー
* サポートされる形式と寸法
|タイプ|サポートされる寸法|サポートされるファイルサイズ|サポートされる形式|
| ---- | ---- | ---- | ---- |
|対象ユーザー画像|推奨: 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
[object Object]
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 統合ガイド](../develo
- [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 統合ガイド](../develo
- [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)