ネイルバーチャル試着

統合ガイド

このガイドでは、次の内容について説明します:

ネイルバーチャル試着 API のワークフロー:

認証が必要: Authorization: Bearer YOUR_API_KEY

ワークフロー手順:

1. 画像アップロードの準備:

   • 手の甲の画像を用意することから始めます。
   • ファイル管理 API の /s2s/v2.0/file を呼び出し、アップロード URL と関連する file_id を取得します。
   • 提供されたアップロード URL を使用して、ネイルのある手の甲の画像をアップロードします。

2. ネイルデザインのセットアップオプション:

   • まず、適したネイルカラーを選択します。お好みに合わせたカスタムシェイプも選択できます。

3. AI タスクの開始とタスク ID の取得:

   • アップロードした画像と選択したエフェクト設定を、HTTP POST リクエストで /s2s/v2.0/task/nail-vto に送信します。
   • この操作を識別する一意のタスク ID をレスポンスで受け取ります。

4. タスクステータスのポーリング（継続的なチェック）:

   • 取得した task_id を使用して、HTTP GET リクエスト（例: GET /s2s/v2.0/task/nail-vto/${task_id}）で定期的にタスクステータスをポーリングします。
   • 以下を継続的に監視します:
     • Task_status = "success"（処理が完了）。
     • Task_status = "error"（該当する場合、解決するか再試行）。
   • ステータスが success に移行したら、ワークフローを適切に更新します。

• API プレイグラウンド

API プレイグラウンドで API を対話的にテストします:

API プレイグラウンド: http://yce.makeupar.com/api-console/en/api-playground/ai-nail-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 を持っている場合は、このステップをスキップできます。

2. エフェクトテンプレートの準備

   • この目的のために、4 つの異なるセットアップモードが用意されています:

     1. カラーをカスタマイズし、現在のネイルルックに合わせる
     2. プリセットデザインと特定のシェイプを使用して、イメージを実現する
     3. プレスオンネイルを追加し、既存の元のネイル画像とリンクする
     4. 一致するプレッスオンネイル製品の画像リンクを提供する

   • エフェクトテンプレートの JSON スキーマ

     {
         "version": "1.0",
         "effect_type": "nail_polish", // valid values: ['nail_polish', 'press_on_nails']
         "effects": [],
         "ref_file_ids": []
     }

     • エフェクト形式

       • ネイルポリッシュ - カラー
       {
           "sub_type": "color",
           "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']
           "color": "#ff0000",
           "texture": "cream", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine']
           "transparency": 0, // 0-100, for textures except metallic
           "reflection": 0, // 0-100
           "contrast": 0, // 0-100
           "roughness": 0, // 0-100
           "shimmer_opacity": 0, // 0-100, for texture pearl
           "shimmer_size": 0, // 0-100, for texture shimmer_coarse and shimmer_fine
           "textured_size": 0, // 0-100, for texture textured
       }

       • ネイルポリッシュ - デザイン
       {
           "sub_type": "design",
           "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']
           "ref_file_url": "",  // Optional; Either ref_file_id or ref_file_url must be filled, but only one can be selected.
           "ref_file_index": 0, // This field is optional unless uploading is selected. Index corresponding to ref_file_ids under the root node
           "texture": "cream", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine']
           "transparency": 0, // 0-100, only for textures except metallic
           "reflection": 0, // 0-100
           "contrast": 0, // 0-100
           "roughness": 0, // 0-100
           "shimmer_opacity": 0, // 0-100, for texture pearl
           "shimmer_size": 0, // 0-100, for texture shimmer_coarse and shimmer_fine
           "textured_size": 0, // 0-100, for texture textured
       }
       

       • プレスオンネイル - カラー
       • 最新のシェイプ値は、https://plugins-media.makeupar.com/wcm-saas/shapes/nails.json で確認できます。
       {
           "sub_type": "color",
           "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']
           "shape": "square_oval", // Please check the nails.json. valid values: ['square_oval','square_square','square_squoval','squoval_oval','squoval_square','squoval_squoval','oval_oval','oval_square','oval_squoval','almond_oval','almond_square','almond_squoval','stiletto_oval','stiletto_square','stiletto_squoval],
           "length": 1.0, // 0.8-2.15, for shapes except original
           "color": "#ff0000",
           "texture": "cream", // valid values for other shapes: ['matte', 'cream', 'metallic']
           "reflection": 0, // 0-100
           "contrast": 0, // 0-100
           "roughness": 0 // 0-100
       }

       • プレスオンネイル - デザイン
       {
           "sub_type": "design",
           "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']
           "ref_file_url": "",  // Optional; Either ref_file_id or ref_file_url must be filled, but only one can be selected.
           "ref_file_index": 0, // This field is optional unless uploading is selected. Index corresponding to ref_file_ids under the root node
           "texture": "cream", // valid values: ['matte', 'cream', 'metallic']
           "reflection": 0, // 0-100
           "contrast": 0, // 0-100
           "roughness": 0, // 0-100
       }
       

   • エフェクトテンプレートのデザインロジック

     1. エフェクトタイプの検出（press_on_nails または nail_polish）。
     2. effects の各エントリを繰り返し:

     sub_type === "color" の場合 → フィールドを直接マッピングし、欠落しているテクスチャ関連のキーをデフォルト値で埋めます。 sub_type === "design" の場合 →

     • ユーザーが ref_file_url を指定した場合は、それを保持し、ref_file_index を 省略します。
     • ユーザーがインデックス (ref_file_index) を指定した場合は、ref_file_ids が存在し、インデックスが有効であることを確認してから、"ref_file_id": ref_file_ids[index] を設定します（省略可 – 一部のバックエンドでは id ではなく生のインデックスを期待します）。
     1. 数値範囲の正規化 – 範囲外の値を 0-100 または長さの制限にクランプします。
     2. スキーマバリデーションを通過できるように、欠落している任意のキーをデフォルト値で追加します。
     3. 最終オブジェクトを JSON として シリアライズ します（デバッグ用に compact または pretty）。

   • 送信準備ができたペイロード例

     {
     "version": "1.0",
     "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/nail_user_photo_01_27d4260646.jpg",
     "effect_type": "press_on_nails",
     "ref_file_ids": [
         "Ks3kh+1nPpVNm8iJb5374CWtBzkT4B44NPJwXbBKqVxfjK3xgCQ+hRt9MJXBFaud",
         "+Z7PSjuzigvsc3S/Yli1A4WN7c3J6NJHFqK2iUlqD2BfjK3xgCQ+hRt9MJXBFaud"
     ],
     "effects": [
         {
         "sub_type": "design",
         "finger": "thumb",
         "texture": "cream",
         "reflection": 100,
         "contrast": 50,
         "roughness": 0,
         "ref_file_index": 0
         },
         {
         "sub_type": "design",
         "finger": "index",
         "texture": "cream",
         "reflection": 100,
         "contrast": 50,
         "roughness": 0,
         "ref_file_index": 1
         },
         {
         "sub_type": "design",
         "finger": "middle",
         "texture": "cream",
         "reflection": 100,
         "contrast": 50,
         "roughness": 0,
         "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_3_9ce2ddc47a.png"
         },
         {
         "sub_type": "design",
         "finger": "pinky",
         "texture": "cream",
         "reflection": 100,
         "contrast": 50,
         "roughness": 0,
         "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_5_f6e46dd56f.png"
         },
         {
         "sub_type": "design",
         "finger": "ring",
         "texture": "cream",
         "reflection": 100,
         "contrast": 50,
         "roughness": 0,
         "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_4_2103ca8cac.png"
         }
     ]
     }

3. ネイル VTO タスクの作成と結果のポーリング

   画像と完全なエフェクトペイロードが揃ったら、タスクを作成します。API はリクエストを非同期で処理します。success または error になるまで、タスクステータスをポーリングする必要があります。

   • タスク作成エンドポイント

     POST /s2s/v2.0/task/nail-vto

   • ポーリングエンドポイント

     GET /s2s/v2.0/task/nail-vto/{task_id}

ファイル仕様とエラー

• ネイルバーチャル試着の仕様

対応ネイルビュー 遮蔽物のない、明確な正面ビューの 1 枚のネイル画像。

プレッスオンネイルデザイン画像サンプル:

対応ハンドビュー

• 入力画像は 1 つの手のみをサポートします
• 手のひらの面積は、入力画像の面積の少なくとも半分であることが望ましいです
• 入力画像のアスペクト比は 1:1、3:4、4:3 が望ましいです
• 指の爪は隠れていないこと
• 爪にネイルチップやネイルポリッシュがないことが望ましいです

• エラーコード

• 環境と依存関係

JS Camera Kit

ユニット消費