# AI ネックレスバーチャル試着

# 概要
ネックレスのバーチャル試着を作成します。
AI の首元と鎖骨トラッキングにより、ネックレスの試着プレビューを生成します。
2D 画像からネックレスのバーチャル試着を作成します。3D モデリングは不要です。
## 統合ガイド
本ガイドでは以下内容を説明します:
* **エンドポイント:**

`/s2s/v2.0/task/2d-vto/necklace`
* **認証:**
 すべてのリクエストに
`Authorization: Bearer YOUR_API_KEY`
 が必要です
* **ワークフロー:**
  1. **セルフィー画像を準備する:**
 画像をアップロードするか、有効な画像 URL を提供します
  2. **ネックレス画像を準備する:**
 画像をアップロードするか、ネックレス製品の有効な画像 URL を提供します
  3. **AI タスクを発行しタスク ID を取得する:**
 レスポンスから
`task_id`
 を取得します。
  4. **ステータスをポーリングする（`GET`）:**

`task_id`
 を使用してタスクのステータスを確認します。
`task_status`
 が
`"success"`
 または
`"error"`
 になるまでポーリングを続行してください。



---

* API プレイグラウンド

API プレイグラウンドで API を対話的にテストします:
**API プレイグラウンド:**
[http://yce.makeupar.com/api-console/en/api-playground/ai-necklace-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-necklace-virtual-try-on/)


---

* 認証

- リクエストヘッダーに
**Bearer Token**
 を使用して API キーを含めます:

```
Authorization: Bearer YOUR_API_KEY
```

API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/.
*   1. 画像のアップロード

ファイルをサーバーに直接アップロードするか、VTO タスクペイロードに有効な画像 URL を提供できます。
* アップロードエンドポイント


```
POST /s2s/v2.0/file
```
すでにパブリックな画像 URL を持っている場合は、このステップをスキップできます。
File API のレスポンスで提供された URL にファイルを直接アップロードし、その後 File API が返した対応する `src_file_id` を使用して AI タスクを呼び出すことができます。または VTO タスクペイロードに有効な画像 URL を `src_file_url` として提供します。`src_file_id` または `src_file_url` がバーチャル試着の対象となります。
また、`src_file_id` または `src_file_url` に適用するネックレス製品画像を参照として `ref_file_ids` または `ref_file_urls` で提供する必要があります。
AI エンジンでは、セルフィーの自動背景透過に対応しています。ただし、首（`srcmsk_file_id` または `srcmsk_file_url`）のオクルージョンマスク画像ファイルを提供してセグメンテーションを微調整できます。


---

*   1. ネックレス VTO タスクの作成と結果のポーリング

画像とテンプレート ID が揃ったら、タスクを作成します。API はリクエストを非同期で処理します。ステータスが `success` または `error` に達するまでタスクステータスをポーリングする必要があります。
* タスク作成エンドポイント


```
POST /s2s/v2.0/task/2d-vto/necklace
```
* ポーリングエンドポイント


```
GET /s2s/v2.0/task/2d-vto/necklace/{task_id}
```


---

## ファイル仕様とエラー
* ネックレスバーチャル試着の仕様

**サポートされるネックレスビュー**
背景を除去した、ネックレスを着用した前面画像。
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/necklace_product_01_124206cfbe_3993a2128d.jpg)
**サポートされるセルフィービュー**
首が明確に見えており、遮蔽のない前面のセルフィー。頭の水平回転は 20 度以内でサポートされます。頭のサイズは比例したものであり、首の幅は画像幅の少なくとも 15 パーセントを占める必要があります。
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Necklace_restriction_83410fb6c1.png)
**necklace_wearing_location: array of two points (optional)**
ネックレスを配置すべき写真内のターゲット位置を指定します。
デフォルト: null（エンジンのデフォルト）
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/wearing_location_874264bb70.jpg)
**necklace_shadow_intensity: float (0.0 to 1.0)**
影の強さを制御します:
0.0 は影なしを示します
1.0 は最大限の影を示します
デフォルト値: 0.15
**necklace_ambient_light_intensity: float (0.0 to 1.0)**
ライティングがセルフィー画像を参照する度合いを定義します:
0.0 はセルフィー画像のライティングを無視します
1.0 はセルフィー画像のライティングと影のレンダリングに完全に一致させます
デフォルト値: 1.0
**ネックレスアンカーポイント: ピクセル座標の 2 点の配列（任意）**
製品画像内のネックレスチェーンの左右に見える端部のアンカーポイントを指定し、アラインメントに使用します。
デフォルト: null（エンジンのデフォルト）
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/anchor_point_7f9b254ca4.jpg)


---

* サポートされる形式と寸法

| AI 機能 | サポートされる寸法 | サポートされるファイルサイズ | サポートされる形式 |
|  --- | --- | --- | --- |
| ネックレスバーチャル試着 | 長辺 <= 4096 | < 10MB | jpg/jpeg/png |

* エラーコード

| エラーコード | 説明 |
|  --- | --- |
| RUNTIME_ERROR | 実行中に予期しないエラーが発生しました |
| PHOTO_DETECTION_FAIL | ユーザー写真が正しく処理できませんでした（例: 首が検出されなかった） |
| OBJECT_DETECTION_FAIL | オブジェクト写真が正しく処理できませんでした（例: 製品が検出されなかった） |
| PHOTO_CHECK_INVALID | ユーザー写真のポーズまたはサイズが無効です |
| INPUT_ERROR | 入力ファイルの形式が正しくありません |
| INPUT_MAIN_IMAGE_EMPTY | ユーザー画像が必要です |

* 環境と依存関係

| サンプルコードの言語/ツール | 推奨ランタイムバージョン |
|  --- | --- |
| 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 |



---

## JS Camera Kit


---

## ユニット消費
| AI 機能 | 消費ユニット |
|  --- | --- |
| ネックレスバーチャル試着 V1.0 | シングルアイテム着用で 1 ユニット |



---

License: Privacy policy

## Servers

```
https://yce-api-01.makeupar.com
```

## Security

### BearerAuthenticationV2

標準の「Bearer 認証」を使用します。ヘッダーに `Authorization:Bearer YOUR_API_KEY` として「API キー」を指定してください。`Bearer` と `YOUR_API_KEY` の間に半角スペースがあることに注意してください。

Type: http
Scheme: bearer

## Download OpenAPI description

 - [AI ネックレスバーチャル試着](https://docs.perfectcorp.com/_bundle/@l10n/ja/reference/ai_necklace.yaml)

## V1.0

 - [POST /s2s/v2.0/task/2d-vto/necklace](https://docs.perfectcorp.com/ja/reference/ai_necklace/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1necklace/post.md): このエンドポイントは、ネックレスのバーチャル試着プロセスを開始します。ソースファイルと参照画像（URL またはファイル ID 経由）、およびアライメント、シャドウ、着用位置のための特定のパラメータを指定する必要があります。タスクは非同期で処理され、このレスポンスで返される `task_id` を使用してステータスを確認できます。
 - [GET /s2s/v2.0/task/2d-vto/necklace/{task_id}](https://docs.perfectcorp.com/ja/reference/ai_necklace/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1necklace~1%7Btask_id%7D/get.md)