# AI バッグバーチャル試着
# 概要
AI バッグで、バッグのバーチャル試着を作成します。
## 統合ガイド
このガイドでは、以下を説明します：
* **エンドポイント:** `/s2s/v2.0/task/bag`
* **認証:** すべてのリクエストには `Authorization: Bearer YOUR_API_KEY` が必要です
* **ワークフロー:**
1. **セルフィー画像の準備:** バーチャル試着対象として、自分の画像をアップロードするか、有効な画像 URL を提供します。
1. **バッグ画像の準備:** バッグ製品、またはバッグを持っている人物（遮るものがない状態）の画像をアップロードするか、有効な画像 URL を提供します。
1. **スタイルと性別の選択:** 希望するスタイルと、視覚化したい性別を選択します。
1. **AI タスクの実行とタスク ID の取得:** レスポンスから `task_id` を取得します。
1. **ステータスのポーリング (`GET`):** `task_id` を使用してタスクのステータスを確認します。`task_status` が `"success"` または `"error"` になるまでポーリングを継続します。
---
* 認証
- **ベアラートークン** を使用して、リクエストヘッダーに API キーを含めます：
```
Authorization: Bearer YOUR_API_KEY
```
API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/.
---
* AI バッグ API 使用ガイド
このガイドでは、画像のアップロード、参照バッグの準備、および AI バッグ API を使用したバーチャル試着タスクの作成方法について説明します。
***
* ステップ 1. ファイル API を使用したファイルのアップロード
**ファイル 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": "selfie_photo_01_3dbd1b6683.jpg",
"file_size": 547541
}
]
}'
```
***
* ステップ 2. ファイル API レスポンスの取得
レスポンスには以下が含まれます：
* AI タスク作成用の `file_id`。
* 実際の画像ファイルをアップロードするための `requests.url`。
**レスポンス例:**
```json
{
"status": 200,
"data": {
"files": [
{
"content_type": "image/jpg",
"file_name": "selfie_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 への画像アップロード
ファイル 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 @'./selfie_photo_01_3dbd1b6683.jpg'
```
***
* ステップ 4. 参照バッグ画像の準備
以下が可能：
* ファイル API (`/s2s/v2.0/file`) を使用してバッグ画像をアップロードする、または
* 有効な画像 URL を提供する。
**サポートされるバッグ画像:**
* バッグの製品画像。
* バッグの参照として、遮るものなくバッグを持っている人物。
詳細な仕様については **[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** を参照してください。
***
* ステップ 5. AI タスクの作成
希望するスタイルと、視覚化したい性別を選択します。
**AI タスク API** (`/s2s/v2.0/task/bag`) を使用してバーチャル試着タスクを作成します。
**パラメータ:**
* ユーザー画像用: `src_file_id` または `src_file_url`。
* バッグ画像用: `ref_file_id` または `ref_file_url`。
**リクエスト例:**
```bash
curl --request POST \
--url https://yce-api-01.makeupar.com/s2s/v2.0/task/bag \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--data '{
"src_file_url": "https://example.com/selfie.jpg",
"ref_file_url": "https://example.com/accessory.jpg",
"gender": "female",
"style": "random"
}'
```
**レスポンス例:**
```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/bag/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \
--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"
}
```
---
## ファイル仕様とエラー
* AI バッグバーチャル試着仕様
**サポートされるバッグ画像**
* 製品画像要件
* 最小解像度: 512 × 512 ピクセル
* 画像あたり 1 つの製品のみ
* 製品は画像の高さの 25 % 以上を占める必要があります
* 着用画像要件
* 最小解像度: 800 × 800 ピクセル
**サポートされるセルフィービュー**
* 推奨画像解像度: 少なくとも 512 × 512 ピクセル。
* 推奨顔の被写体範囲: 画像の高さの 15 % 以上。
* 画像には、顔全体がはっきりと見え、頭から胸まで少なくとも頭部ショットが含まれる単一の人物が写っている必要があります。半身ショットが推奨されます。
**試着スタイル**
* バーチャル試着出力を生成するための 4 つの事前定義スタイルがあります: "style_parisian_chic", "style_urban_chic", "style_mediterranean_chic", "style_art_deco_style"。AI タスク作成時にこのスタイルパラメータを指定するか、デフォルトでシステムがランダムにスタイルを選択するようにできます。
---
* サポートされる形式と寸法
|AI 機能|サポートされる寸法|サポートされるファイルサイズ|サポートされる形式|
| ---- | ---- | ---- | ---- |
|AI バッグバーチャル試着|入力: 長辺 <= 4096
出力: 1104 x 1472 |< 10MB|jpg/jpeg/png/heic|
* エラーコード
|エラーコード|説明|
| ---- | ---- |
| error_download_image | srcKeys/refKeys のダウンロードエラー |
| error_inference | 推論パイプラインエラー |
| error_no_face | ソース画像で顔が検出されませんでした |
| error_nsfw_content_detected| 結果画像で NSFW コンテンツが検出されました |
| exceed_max_filesize | 入力ファイルサイズが最大制限 (10 MB) を超えています |
| invalid_parameter | 無効な性別オプション値
無効なスタイルオプション値 |
| unknown_internal_error | その他 |
* 環境と依存関係
| サンプルコード言語 / ツール | 推奨ランタイムバージョン |
|---|---|
| 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 機能 | 消費ユニット |
|---|---|
| AI バッグバーチャル試着 V2.0 | 2 |
---
License: Privacy policy
## Servers
```
https://yce-api-01.makeupar.com
```
## Security
### BearerAuthenticationV2
[object Object]
Type: http
Scheme: bearer
## Download OpenAPI description
- [AI バッグバーチャル試着](https://docs.perfectcorp.com/_bundle/@l10n/ja/reference/ai_bag.yaml)
## V2.0
- [POST /s2s/v2.0/task/bag](https://docs.perfectcorp.com/ja/reference/ai_bag/v2.0/paths/~1s2s~1v2.0~1task~1bag/post.md): このエンドポイントは、バッグバーチャル試着プロセスを開始します。ソースファイル、参照ファイル（URL または ID）、および性別とスタイルパラメータを指定する必要があります。タスクは非同期で処理され、このレスポンスで返される task_id を使用してステータスを確認できます。
- [GET /s2s/v2.0/task/bag/{task_id}](https://docs.perfectcorp.com/ja/reference/ai_bag/v2.0/paths/~1s2s~1v2.0~1task~1bag~1%7Btask_id%7D/get.md)