AI 肌分析

統合ガイド (Integration Guide)

• AI 肌分析のための写真の撮影方法

• 真正面を向いてセルフィーを撮影する

  • 1 枚の鮮明な写真を、カメラをまっすぐ見つめて撮影します。髪は下ろして胸にかかるようにし、真正面の構図になるよう必ずまっすぐ前方を見てください。
  • 代わりに JS Camera Kit を使用して撮影します。髪は下ろして胸にかかるようにするだけで構いません。まとめないでください。

• ワークフロー 肌診断 API 使用ガイド このガイドでは、File API と AI Task API を使用して画像をアップロードし、肌診断タスクを作成する方法を説明します。

  • ステップ 1: 元画像をリサイズする
    写真を対応寸法に合わせてリサイズします - SD は長辺が最大 4096 ピクセルで短辺が 480 ピクセル以上、または HD は長辺が最大 4096 ピクセルで短辺が 1080 ピクセル以上です。詳細は ファイル仕様とエラー を参照してください

  • ステップ 2: File API でファイルメタデータをアップロードする

• 画像の要件
  • 詳細は ファイル仕様とエラー を参照してください

POST リクエストを送信して、ファイルアップロードを初期化します：

• 重要: File API を呼び出すだけではファイルはアップロードされません。File API のレスポンスで提供される URL に対してファイルを追加でアップロードする必要があります。その URL がアップロード先です。次に進む前に、ファイルが正常に転送されたことを確認してください。

  警告: File API のレスポンスで提供される URL にファイルをアップロードしないまま AI API を使用すると、500 Server Error / unknown_internal_error または 404 Not Found エラーが発生します。

• ステップ 3: アップロード URL とファイル ID を取得する

レスポンスには以下が含まれます：

• requests.url – 画像アップロード用のプリサインド URL。
• file_id – AI タスク作成用の識別子。

レスポンス例：

• ステップ 4: プリサインド URL に画像をアップロードする

提供された requests.url とヘッダーを使用します：

• ステップ 5: AI タスクを作成する

ステップ 2 の file_id を使用して肌診断タスクを作成します：

アップロードが完了したら、ファイル ID または画像ファイル URL を使用して、解析する肌悩みを選択できます。入力と出力 を参照してください。
その後、ファイル ID または画像ファイル URL を指定して POST 'task/skin-analysis' を呼び出すと画質改善タスクが実行され、task_id が取得されます。 SD と HD の肌悩みパラメータを同時に使用することはサポートされていません。

• 既存の公開画像 URL を使用する アップロードの代わりに、AI タスクの開始時に公開アクセス可能な画像 URL を直接指定できます。

レスポンス例：

• ステップ 6: タスクステータスをポーリングする

task_id を使用してタスクの結果を取得します：

この task_id は、GET 'task/skin-analysis' をポーリングして現在のエンジンステータスを取得し、タスクのステータスを監視するために使用します。エンジンがタスクを完了するまでステータスは 'running' のままとなり、この段階ではユニットは消費されません。

処理された結果は完了後 24 時間保持されます。- 短い間隔でポーリングする必要はありません。- 24 時間以内の範囲であればポーリング間隔は柔軟に設定できます。

重要: 実行時間は保証されないため、タスクステータスを確認するには引き続きポーリングが必要です。

エンジンが入力ファイルの処理に成功し、結果画像を生成すると、タスクは 'success' ステータスに変わります。処理済み画像の URL と dst_id が取得され、結果画像を再アップロードせずに別の AI タスクを連鎖して実行できます。

ユニットが消費されるのはこの場合のみです。エンジンがタスクの処理に失敗すると、タスクのステータスは 'error' に変わり、ユニットは消費されません。 ユニットを減算する際、システムは有効期限が近いものを優先します。有効期限が同じ場合は、最も早く取得したユニットから減算されます。

• ステップ 7: 結果を解釈する

レスポンスには以下が含まれます：

• ui_score – ユーザー向けのスコア。
• raw_score – 解析の生スコア。
• mask_urls – 検出マスクの URL。

レスポンス例：

• デバッグガイド

警告: SD と HD の肌悩みパラメータを同時に使用することはサポートされていません。これらの仕様に違反する操作を行うと InvalidParameters エラーが発生します。

• HD と SD の肌悩みを混在して使用すると、次のようなエラーが発生します：
  {
      "status": 400,
      "error": "cannot mix HD and SD dst_actions",
      "error_code": "InvalidParameters"
  }

• 肌悩みをスペルミスした場合、または不明な肌悩みを送信した場合、次のようなエラーが発生します：
  {
      "status": 400,
      "error": "Not available dst_action abc123",
      "error_code": "InvalidParameters"
  }

• 実際の活用例：

入力と出力 (Inputs & Outputs)

• 入力パラメータの説明 AI 肌分析 (AI Skin Analysis) の結果の視覚的な出力を制御する方法は 2 つあります。複数の画像を生成して各肌悩みをそれぞれ独立したマスクとして表示する方法と、enable_mask_overlay パラメータを使用してブレンドされた 1 枚の画像を生成する方法のいずれかを選択できます。初期設定ではシステムが複数のマスクを出力するため、各肌悩みのマスクを画像とどのようにブレンドするかを完全に制御できます。

• 初期値: enable_mask_overlay false

• enable_mask_overlay を true に設定

• 出力 ZIP のデータ構造の説明 システムは ZIP ファイルを提供し、その内部に 'skinanalysisResult' フォルダが含まれています。このフォルダには、すべての検出スコアと結果画像への参照を含む 'score_info.json' ファイルが格納されています。

'score_info.json' ファイルには、すべての肌診断の検出結果が、数値のスコアと対応する出力マスクファイル名とともに含まれています。

PNG ファイルは、元の画像にオーバーレイできる検出結果のマスクです。これらの PNG ファイルのアルファ値を使って元の画像とブレンドするだけで、検出結果を元画像上で直接確認できます。

• 肌診断結果 ZIP 内のファイル構成

• HD Skincare ZIP

  • skinanalysisResult
    • score_info.json
    • hd_acne_output.png
    • hd_age_spot_output.png
    • hd_dark_circle_output.png
    • hd_droopy_lower_eyelid_output.png
    • hd_droopy_upper_eyelid_output.png
    • hd_eye_bag_output.png
    • hd_firmness_output.png
    • hd_moisture_output.png
    • hd_oiliness_output.png
    • hd_radiance_output.png
    • hd_redness_output.png
    • hd_texture_output.png
    • hd_pore_output_all.png
    • hd_pore_output_cheek.png
    • hd_pore_output_forehead.png
    • hd_pore_output_nose.png
    • hd_wrinkle_output_all.png
    • hd_wrinkle_output_crowfeet.png
    • hd_wrinkle_output_forehead.png
    • hd_wrinkle_output_glabellar.png
    • hd_wrinkle_output_marionette.png
    • hd_wrinkle_output_nasolabial.png
    • hd_wrinkle_output_periocular.png
    • hd_tear_trough.png
    • hd_skin_type.png

• SD Skincare ZIP

  • skinanalysisResult
    • score_info.json
    • acne_output.png
    • age_spot_output.png
    • dark_circle_v2_output.png
    • droopy_lower_eyelid_output.png
    • droopy_upper_eyelid_output.png
    • eye_bag_output.png
    • firmness_output.png
    • moisture_output.png
    • oiliness_output.png
    • pore_output.png
    • radiance_output.png
    • redness_output.png
    • texture_output.png
    • wrinkle_output.png
    • tear_trough.png
    • skin_type.png

• JSON データ構造 (score_info.json)

  • "all": 1 から 100 の範囲の浮動小数点値で、一般的な肌状態を表します。スコアが高いほど、より健康で美しさに優れた肌状態であることを示します。

  • "skin_age": すべての年齢層にわたる一般母集団の分布に対する、AI が算出した肌年齢。

  • 各カテゴリには以下が含まれます:

    • "raw_score": 1 から 100 の範囲の浮動小数点値。スコアが高いほど、より健康で美しさに優れた肌状態であることを示します。
    • "ui_score": 1 から 100 の範囲の整数。UI Score は主に美容評価において心理的なモチベーションの向上として機能します。消費者は一般的に自身の肌状態について肯定的な評価を好むことを踏まえ、より好ましい結果となるよう raw スコアを調整しています。このキャリブレーションは、根底にある美容心理学の枠組みを維持しつつ、ユーザーにより大きな自信を持っていただくことを目的としています。
    • "output_mask_name": 対応する出力マスク画像のファイル名。

  • カテゴリと説明

    • HD Skincare:

      • "hd_redness": 肌の赤みの深刻度を測定します。
      • "hd_oiliness": 肌の皮脂レベルを判定します。
      • "hd_age_spot": 老人斑と色素沈着を検出します。
      • "hd_radiance": 肌の輝きを評価します。
      • "hd_moisture": 肌の水分量を評価します。
      • "hd_dark_circle": 目の下のクマの有無を解析します。
      • "hd_eye_bag": 目元のたるみを検出します。
      • "hd_droopy_upper_eyelid": 上まぶたの下垂の深刻度を測定します。
      • "hd_droopy_lower_eyelid": 下まぶたの下垂の深刻度を測定します。
      • "hd_firmness": 肌のハリと弾力を評価します。
      • "hd_texture": Subcategories[whole]; 肌全体のキメを解析します。
      • "hd_acne": Subcategories[whole]; にきりの有無を検出します。
      • "hd_pore": Subcategories[forehead, nose, cheek, whole]; 異なる顔領域の毛穴を検出し、評価します。
      • "hd_wrinkle": Subcategories[forehead, glabellar, crowfeet, periocular, nasolabial, marionette, whole]; さまざまな顔領域におけるしわの深刻度を測定します。
      • "hd_tear_trough": 涙溝を検出します。
      • "hd_skin_type": Subcategories[whole, t_zone, u_zone] Normal、Oily、Dry、Combination、Redness、Dry & Redness、Oily & Redness、Combination & Redness のいずれかの肌タイプを評価します。

    • SD Skincare:

      • "wrinkle": しわに関する一般的な解析。
      • "droopy_upper_eyelid": 上まぶたの下垂の深刻度を測定します。
      • "droopy_lower_eyelid": 下まぶたの下垂の深刻度を測定します。
      • "firmness": 肌のハリと弾力を評価します。
      • "acne": にきりの有無を評価します。
      • "moisture": 肌の水分量を測定します。
      • "eye_bag": 目元のたるみを検出します。
      • "dark_circle_v2": 別の方法を用いてクマを解析します。
      • "age_spot": 老人斑を検出します。
      • "radiance": 肌の明るさを評価します。
      • "redness": 肌の赤みを測定します。
      • "oiliness": 肌の皮脂レベルを判定します。
      • "pore": 毛穴の目立ち度を測定します。
      • "texture": 肌全体のキメを解析します。
      • "tear_trough": 涙溝を検出します。
      • "skin_type": Subcategories[whole, t_zone, u_zone] Normal、Oily、Dry、Combination、Redness、Dry & Redness、Oily & Redness、Combination & Redness のいずれかの肌タイプを評価します。

  • HD Skincare の score_info.json の例

    {
        "hd_redness": {
            "raw_score": 72.011962890625,
            "ui_score": 77,
            "output_mask_name": "hd_redness_output.png"
        },
        "hd_oiliness": {
            "raw_score": 60.74365234375,
            "ui_score": 72,
            "output_mask_name": "hd_oiliness_output.png"
        },
        "hd_age_spot": {
            "raw_score": 83.23274230957031,
            "ui_score": 77,
            "output_mask_name": "hd_age_spot_output.png"
        },
        "hd_radiance": {
            "raw_score": 76.57244205474854,
            "ui_score": 79,
            "output_mask_name": "hd_radiance_output.png"
        },
        "hd_moisture": {
            "raw_score": 48.694559931755066,
            "ui_score": 70,
            "output_mask_name": "hd_moisture_output.png"
        },
        "hd_dark_circle": {
            "raw_score": 80.1993191242218,
            "ui_score": 76,
            "output_mask_name": "hd_dark_circle_output.png"
        },
        "hd_eye_bag": {
            "raw_score": 76.67280435562134,
            "ui_score": 79,
            "output_mask_name": "hd_eye_bag_output.png"
        },
        "hd_droopy_upper_eyelid": {
            "raw_score": 79.05348539352417,
            "ui_score": 80,
            "output_mask_name": "hd_droopy_upper_eyelid_output.png"
        },
        "hd_droopy_lower_eyelid": {
            "raw_score": 79.97175455093384,
            "ui_score": 81,
            "output_mask_name": "hd_droopy_lower_eyelid_output.png"
        },
        "hd_firmness": {
            "raw_score": 89.66898322105408,
            "ui_score": 85,
            "output_mask_name": "hd_firmness_output.png"
        },
        "hd_texture": {
            "whole": {
                "raw_score": 66.3921568627451,
                "ui_score": 75,
                "output_mask_name": "hd_texture_output.png"
            }
        },
        "hd_acne": {
            "whole": {
                "raw_score": 59.92677688598633,
                "ui_score": 76,
                "output_mask_name": "hd_acne_output.png"
            }
        },
        "hd_pore": {
            "forehead": {
                "raw_score": 79.59770965576172,
                "ui_score": 80,
                "output_mask_name": "hd_pore_output_forehead.png"
            },
            "nose": {
                "raw_score": 29.139814376831055,
                "ui_score": 58,
                "output_mask_name": "hd_pore_output_nose.png"
            },
            "cheek": {
                "raw_score": 44.11081314086914,
                "ui_score": 65,
                "output_mask_name": "hd_pore_output_cheek.png"
            },
            "whole": {
                "raw_score": 49.23978805541992,
                "ui_score": 67,
                "output_mask_name": "hd_pore_output_all.png"
            }
        },
        "hd_wrinkle": {
            "forehead": {
                "raw_score": 55.96956729888916,
                "ui_score": 67,
                "output_mask_name": "hd_wrinkle_output_forehead.png"
            },
            "glabellar": {
                "raw_score": 76.7251181602478,
                "ui_score": 75,
                "output_mask_name": "hd_wrinkle_output_glabellar.png"
            },
            "crowfeet": {
                "raw_score": 83.4361481666565,
                "ui_score": 78,
                "output_mask_name": "hd_wrinkle_output_crowfeet.png"
            },
            "periocular": {
                "raw_score": 67.88706302642822,
                "ui_score": 72,
                "output_mask_name": "hd_wrinkle_output_periocular.png"
            },
            "nasolabial": {
                "raw_score": 74.03312683105469,
                "ui_score": 74,
                "output_mask_name": "hd_wrinkle_output_nasolabial.png"
            },
            "marionette": {
                "raw_score": 71.94477319717407,
                "ui_score": 73,
                "output_mask_name": "hd_wrinkle_output_marionette.png"
            },
            "whole": {
                "raw_score": 49.64699745178223,
                "ui_score": 65,
                "output_mask_name": "hd_wrinkle_output_all.png"
            }
        },
        "all": {
            "score": 75.75757575757575
        },
        "skin_age": 37
    }

  • SD Skincare の score_info.json の例

    {
        "wrinkle": {
            "raw_score": 36.09360456466675,
            "ui_score": 60,
            "output_mask_name": "wrinkle_output.png"
        },
        "droopy_upper_eyelid": {
            "raw_score": 79.05348539352417,
            "ui_score": 80,
            "output_mask_name": "droopy_upper_eyelid_output.png"
        },
        "droopy_lower_eyelid": {
            "raw_score": 79.97175455093384,
            "ui_score": 81,
            "output_mask_name": "droopy_lower_eyelid_output.png"
        },
        "firmness": {
            "raw_score": 89.66898322105408,
            "ui_score": 85,
            "output_mask_name": "firmness_output.png"
        },
        "acne": {
            "raw_score": 92.29713000000001,
            "ui_score": 88,
            "output_mask_name": "acne_output.png"
        },
        "moisture": {
            "raw_score": 48.694559931755066,
            "ui_score": 70,
            "output_mask_name": "moisture_output.png"
        },
        "eye_bag": {
            "raw_score": 76.67280435562134,
            "ui_score": 79,
            "output_mask_name": "eye_bag_output.png"
        },
        "dark_circle_v2": {
            "raw_score": 80.1993191242218,
            "ui_score": 76,
            "output_mask_name": "dark_circle_v2_output.png"
        },
        "age_spot": {
            "raw_score": 83.23274230957031,
            "ui_score": 77,
            "output_mask_name": "age_spot_output.png"
        },
        "radiance": {
            "raw_score": 76.57244205474854,
            "ui_score": 79,
            "output_mask_name": "radiance_output.png"
        },
        "redness": {
            "raw_score": 72.011962890625,
            "ui_score": 77,
            "output_mask_name": "redness_output.png"
        },
        "oiliness": {
            "raw_score": 60.74365234375,
            "ui_score": 72,
            "output_mask_name": "oiliness_output.png"
        },
        "pore": {
            "raw_score": 88.38014125823975,
            "ui_score": 84,
            "output_mask_name": "pore_output.png"
        },
        "texture": {
            "raw_score": 80.09742498397827,
            "ui_score": 76,
            "output_mask_name": "texture_output.png"
        },
        "all": {
            "score": 75.75757575757575
        },
        "skin_age": 37
    }

ファイル仕様とエラー (File Specs and Errors)

• 対応しているファイル形式と解像度

警告: API では画像が自動的に最大 2560 ピクセルにリサイズされますが、すべての顔にはっきりとピントが合っていること、画像の品質が高いこと、照明が均一であること、顔のサイズが十分に大きく、カメラの正面を向いていることを、お客様ご自身の責任でご確認ください。AI 肌分析 (AI Skin Analysis) を実行する前に HD または SD のスキンケア画像を撮影する際は、被写体ブレと遮蔽を避けてください。最適な結果を得るには、横位置よりも縦位置のアスペクト比の使用を推奨します。

• 撮影方法の推奨事項:

• 肌診断を開始する準備ガイド

• 眼鏡を外し、前髪が額にかかっていないことを確認してください

• 明るい環境であることを確認してください

• より正確な結果を得るためにメイクを落としてください

• カメラをまっすぐ見つめ、顔を中央に保ってください

• 写真の要件 画像の品質を確認し、AI 肌分析に適しているかどうかを判断します。顔が画像の幅の約 60–80% を占め、オーバーレイや遮蔽物がないようにしてください。照明は明るく均一に分配し、露出オーバーや白飛びを避けてください。姿勢は正面を向き、自然でリラックスした状態とし、口を閉じて目を開けてください。

額が完全に見えるようにし、最良の品質を確保するため、前髪を後ろにとかすか髪を結んでください。AI 肌分析の性能を最適化するには眼鏡を外すことを推奨しますが、必須ではありません。

警告: 顔の幅は画像の幅の 60% より大きい必要があります。

• エラーコード

• 環境と依存関係

JS Camera Kit

Mobile Camera Kit

ユニット消費量

• AI 肌分析 (AI Skin Analysis) (V2.0, 2.1)