髪型シミュレーション

概要

AI 髪型シミュレーションで、さまざまな髪型を試します。カール、ロング、ベリーショートなどのスタイルに対応しています。

統合ガイド

API プレイグラウンド API プレイグラウンドで AI 髪型シミュレーション機能をテストします。

API プレイグラウンドにアクセスするには： https://yce.makeupar.com/api-console/en/api-playground/ai-hair-style-generator/

API ワークフローこのガイドでは、AI 髪型シミュレーション API のワークフローを説明します。

エンドポイント: /s2s/v2.1/task/hair-transfer

認証必須: Authorization: Bearer YOUR_API_KEY

ワークフロー手順:

画像アップロード準備:
- プロセスはセルフィーの準備から始まります。
プリセットテンプレートのリスト取得、または独自のリファレンス写真の使用 リファレンスソースの選択 スタイル参照には 2 つのオプションがあります。

オプション	使用ケース	実装ヒント
プリセットテンプレート (`template_id`)	迅速な開始（例：「カールボブ」、「サイドスウェプトバングス」）	`/s2s/v2.1/task/template/hair-transfer` を呼び出し、`template_id` を選択します。
カスタムリファレンス画像 (`ref_file_url` / `ref_file_id`)	ユーザーが自身のスタイル写真をアップロード、または提供された画像リンクを使用	同じファイル API を介してアップロードします。リファレンス画像がすでにオンラインでホストされている場合は `ref_file_url` を使用します。

AI タスクの開始とタスク ID の取得:
- アップロードした画像とスタイル設定を HTTP POST リクエストで /s2s/v2.0/file に送信します。
- このインタラクションを識別する一意のタスク ID をレスポンスで待ちます。
タスクステータスのポーリング（継続的な確認）:
- 取得した task_id を使用して、HTTP GET リクエスト（例：GET /task/${task_id}）でタスクステータスを定期的にポーリングします。
- 以下を継続的に監視します。
  - Task_status = "success"（処理完了）。
  - Task_status = "error"（該当する場合は解決または再試行）。
- ステータスが成功に遷移したら、ワークフローを適切に更新します。

認証

Bearer トークン を使用して、リクエストヘッダーに API キーを含めます。
```
Authorization: Bearer YOUR_API_KEY
```

API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/.

API 使用ガイド

このガイドでは、画像のアップロード、リファレンス画像の準備、および AI 髪型シミュレーション API を使用したバーチャル試着タスクの作成方法について説明します。

ステップ 1. ファイル API を使用したファイルのアップロード、または有効な画像 URL の提供

ファイル API (/s2s/v2.0/file) を使用して、対象ユーザーの画像をアップロードします。

すでに公開されている画像 URL がある場合は、ステップ 1〜3 をスキップできます。

画像要件:

高解像度のセルフィー写真をアップロードします。
写真に全身がはっきりと映っていることを確認します。
複数の人物や邪魔なオブジェクトがある背景は避けてください。

リクエスト例:

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_01_3dbd1b6683.jpg",
        "file_size": 547541
      }
    ]
  }'

ステップ 2. ファイル API レスポンスの取得

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

AI タスク作成用の file_id。
実際の画像ファイルをアップロードするための requests.url。

レスポンス例:

{
  "status": 200,
  "data": {
    "files": [
      {
        "content_type": "image/jpg",
        "file_name": "full_body_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 を使用して画像をアップロードします。

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 @'./full_body_photo_01_3dbd1b6683.jpg'

ステップ 4. リファレンス画像の準備
- 4.1 プリセット画像テンプレートの取得

テンプレート API (/s2s/v2.1/task/template/hair-transfer) を使用して、プリセットリファレンステンプレートのリストを取得します。

curl --request GET \
  --url 'https://yce-api-01.makeupar.com/s2s/v2.1/task/template/hair-transfer?page_size=20&starting_token=73a3c9e69b89' \
  --header 'Authorization: Bearer YOUR_API_KEY'

4.2 リファレンス画像のアップロード

以下が可能になります。

ファイル API (/s2s/v2.0/file) を使用してリファレンス画像をアップロードする、または
有効な画像 URL を提供する。

サポートされる画像:

リファレンス画像としての別のセルフィー写真。

詳細な仕様については ファイル仕様とエラー を参照してください。

ステップ 5. AI 髪型シミュレーションタスクの作成

AI タスク API (/s2s/v2.1/task/hair-transfer) を使用して、バーチャル試着タスクを作成します。

パラメータ:

ユーザー画像用： src_file_id または src_file_url。
リファレンス画像用： ref_file_id、ref_file_url、または template_id。

リクエスト例:

curl --request POST \
  --url https://yce-api-01.makeupar.com/s2s/v2.1/task/hair-transfer \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/selfie_03_cccd5d4803.jpeg",
    "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/style_reference_full_body_01_5a000d999f.png"
  }'

レスポンス例:

{
  "status": 200,
  "data": {
    "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT"
  }
}

ステップ 6. タスク結果のポーリング

タスク ID を使用してステータスを確認します。

curl --request GET \
  --url https://yce-api-01.makeupar.com/s2s/v2.1/task/hair-transfer/<YOUR_TASK_ID> \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json'

ステップ 7. 結果の取得

成功したレスポンスには、結果画像のダウンロード URL が含まれます。

{
  "status": 200,
  "data": {
    "error": null,
    "results": {
      "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..."
    },
    "task_status": "success"
  }
}

無効な API キーエラーレスポンス：

{
  "status": 401,
  "error": "Unauthorized",
  "error_code": "InvalidAccessToken"
}

ユースケース：ユースケース：

撮影方法の提案：

ファイル仕様とエラー

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

AI 機能	サポートされる寸法	サポートされるファイルサイズ	サポートされる形式
AI 髪型シミュレーション	長辺 <= 1024、顔幅 >= 128、顔のポーズ: -10 < pitch < +10, -45 < yaw < +45, -15 < roll < +15、単一の顔のみ、顔全体が見える必要がある	< 10MB	jpg/jpeg

エラーコード

エラーコード	説明
error_no_shoulder	ソース画像に肩が見えません
error_large_face_angle	アップロードされた画像の顔の角度が大きすぎます
error_insufficient_landmarks	ソース画像で十分な顔または体のランドマークを検出できません
error_hair_too_short	入力された髪が短すぎます
error_face_pose	ソース画像の顔のポーズはサポートされていません

環境と依存関係

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

FAQ

Q: カスタムの髪型を試すことはできますか？

A: はい、独自のリファレンス写真を使用してカスタムの髪型を試すことができます。AI 髪型シミュレーションでは、希望する髪型を指定するための 2 つの方法をサポートしています。

独自のリファレンス画像のアップロード ファイル API (/s2s/v2.0/file) を介して、高解像度のセルフィーやスタイル写真（例：ターゲットの髪型をしている人物）をアップロードできます。アップロード後、AI タスク作成時に返された file_id または公開 URL をリファレンスソースとして使用します。
有効な画像 URL の提供 リファレンス画像がすでにオンラインでホストされている場合（例：独自サーバーや CDN 上）、リクエストボディの ref_file_url フィールドに HTTPS URL を直接指定できます。

/s2s/v2.1/task/hair-transfer を介してタスクを送信する際は、以下を含めます。

src_file_id（セルフィー）と ref_file_id（カスタムリファレンス画像）、または
src_file_url と ref_file_url。

両方の画像が指定された要件を満たしていることを確認してください。

サポートされる形式：JPG/JPEG のみ
ファイルサイズは 10 MB 未満
長辺 ≤ 1024 ピクセル
顔幅 ≥ 128 ピクセル
頭のポーズが許容範囲内（pitch: −10°〜+10°, yaw: −45°〜+45°, roll: −15°〜+15°）
単一の顔が見え、髪がはっきり見える正面からの完全なビュー

プリセットテンプレートだけでなく、写真リファレンスからも髪型を指定できます。

ユニット消費量

AI 機能	消費ユニット
AI Hair Style Virtual Try-On V2.0	プリセットモードで 1 ユニットカスタムモードで 2 ユニット
AI Hair Style Virtual Try-On V2.1	プリセットモードで 2 ユニットカスタムモードで 2 ユニット

OpenAPI記述をダウンロード

ai_hairstyle.json

ai_hairstyle.yaml

概要

メール

YouCamOnlineEditor_API@perfectcorp.com

ライセンス

利用規約

言語

サーバー

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