# イヤリングバーチャル試着 # 概要 イヤリングバーチャル試着 イヤリング試着とピアシング試着のプレビューを作成します。 2D 画像からイヤリングバーチャル試着を作成します。3D モデリングは不要です。 ## 統合ガイド 本ガイドでは以下内容を説明します: * **エンドポイント:** `/s2s/v2.0/task/2d-vto/earring` * **認証:** すべてのリクエストに `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-earring-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-earring-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`）またはイヤリング製品（`refmsk_file_ids` または `refmsk_file_urls`）のオクルージョンマスク画像ファイルを提供してセグメンテーションを微調整できます。 --- * 1. イヤリング VTO タスクの作成と結果のポーリング 画像とテンプレート ID が揃ったら、タスクを作成します。API はリクエストを非同期で処理します。ステータスが `success` または `error` に達するまでタスクステータスをポーリングする必要があります。 * タスク作成エンドポイント ``` POST /s2s/v2.0/task/2d-vto/earring ``` * ポーリングエンドポイント ``` GET /s2s/v2.0/task/2d-vto/earring/{task_id} ``` --- ## ファイル仕様とエラー * イヤリングバーチャル試着の仕様 **サポートされるイヤリング参照画像** * 遮蔽のない明瞭な前面ビューの単一のイヤリング画像。 * すべてのパラメータ（アンカーポイント、マスク、位置などを含む）は、参照画像が **片方のイヤリング** を着用している場合のみ適用されます。 * 試着の参照画像に **両方のイヤリング** が表示されている場合、すべてのパラメータは **自動検出とデフォルト設定** を使用します。 * **両方のイヤリング** を試着する場合、より明瞭な耳がソースとして使用され、もう片方の耳はミラーリングによって生成されます。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/earring_product_01_41c943f9fc_037ffb1241.jpg) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/earring_product_07_5476e0a156_a69e8e6549.jpg) **サポートされるセルフィービュー** * イヤリングバーチャル試着は前面画像に対応していますが、最も良い結果は横顔の画像で得られます。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Earring_restriction_cdf1de3c7b.png) **earring_wearing_location: integer array of size 2** セルフィー内でイヤリングを配置すべきターゲット位置を指定します。 デフォルト値: null（エンジンのデフォルト） ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/wearing_location_b4f6f4453a.jpg) **earring_scale: number greater than 0** センチメートルでイヤリングのサイズを制御します。 デフォルト値: null（エンジンのデフォルト） **earring_is_right_ear: boolean** イヤリングが右耳に装着されているかどうかを示します。デフォルトでは右耳に装着されます。 デフォルト値: true **earring_occluded_type: number (Enum: 0, 1, 2)** オクルージョンの種類を指定します: 0 は自動検出を意味します 1 は遮蔽ありを意味します 2 は遮蔽なしを意味します デフォルト値: 0 **earring_shadow_intensity: float (0.0 to 1.0)** 影の強さを制御します: 0.0 は影なしを示します 1.0 は最大限の影を示します デフォルト値: 0.15 **earring_ambient_light_intensity: float (0.0 to 1.0)** ライティングがセルフィー画像を参照する度合いを定義します: 0.0 はセルフィー画像のライティングを無視します 1.0 はセルフィー画像のライティングと影のレンダリングに完全に一致させます デフォルト値: 1.0 **イヤリングアンカーポイント: ピクセル座標の 1 点の配列（任意）** イヤリング製品画像内の装着位置を指定します。 デフォルト値: null（エンジンのデフォルト） ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/anchor_point_787282aa19.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 ユニット スタック着用で 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_earrings.yaml) ## V1.0 - [POST /s2s/v2.0/task/2d-vto/earring](https://docs.perfectcorp.com/ja/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring/post.md): このエンドポイントはイヤリングのバーチャル試着プロセスを開始します。ソースファイルと参照画像（URL またはファイル ID 経由）に加え、アライメント、シャドウ、装着位置のための特定のパラメータを指定する必要があります。タスクは非同期で処理され、このレスポンスで返される task_id を使用してステータスを確認できます。 - [GET /s2s/v2.0/task/2d-vto/earring/{task_id}](https://docs.perfectcorp.com/ja/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring~1%7Btask_id%7D/get.md)