帽子バーチャル試着

概要

帽子バーチャル試着を作成します。帽子を着用した状態のプレビューを確認できます。

統合ガイド

このガイドでは、以下を説明します。

エンドポイント: /s2s/v2.0/task/hat
認証: すべてのリクエストで Authorization: Bearer YOUR_API_KEY が必要です
ワークフロー:
1. セルフィー画像の準備: バーチャル試着のターゲットとして、ご自身の画像をアップロードするか、有効な画像 URL を指定します。
2. 帽子画像の準備: 帽子の商品画像または帽子を着用した人物の写真をアップロードします。
3. スタイルと性別の選択: 希望するスタイルと、ビジュアライズしたい性別を選択します。
4. AI タスクの実行とタスク ID の取得: レスポンスから task_id を取得します。
5. ステータスのポーリング (GET): task_id を使用してタスクのステータスを確認します。task_status が "success" または "error" になるまでポーリングを続けます。

認証

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

Authorization: Bearer YOUR_API_KEY

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

AI 帽子 API 使用ガイド

このガイドでは、画像のアップロード、参照用帽子の準備、および AI 帽子 API を使用したバーチャル試着タスクの作成方法について説明します。

ステップ 1. セルフィー画像の準備

以下のいずれかの方法が可能です。

File API (/s2s/v2.0/file) を使用してセルフィー画像をアップロードする、または
有効な画像 URL を指定する。
- ステップ 1.1 File API を使用したファイルのアップロード

File API (/s2s/v2.0/file) を使用して、ターゲットユーザーの画像をアップロードします。

画像要件:

セルフィー写真をアップロードします。
写真に上半身がはっきりと写っていることを確認してください。
複数の人物や気が散るオブジェクトがある背景は避けてください。

リクエスト例:

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

ステップ 1.2. File API レスポンスの取得

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

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

レスポンス例:

{
  "status": 200,
  "data": {
    "files": [
      {
        "content_type": "image/jpg",
        "file_name": "selfie_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"
            }
          }
        ]
      }
    ]
  }
}

ステップ 1.3. 指定された URL への画像アップロード

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

ステップ 2. 参照用帽子画像の準備

以下のいずれかの方法が可能です。

File API (/s2s/v2.0/file) を使用して帽子画像をアップロードする、または
有効な画像 URL を指定する。

サポートされる帽子画像:

帽子の商品画像。
帽子を着用した人物の写真。

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

ステップ 3. AI タスクの作成

希望するスタイルと、ビジュアライズしたい性別を選択します。 AI タスク API (/s2s/v2.0/task/hat) を使用して、バーチャル試着タスクを作成します。

パラメータ:

ユーザー画像用: src_file_id または src_file_url。
帽子画像用: ref_file_id または ref_file_url。

リクエスト例:

curl --request POST \
  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/hat \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "src_file_url": "https://example.com/selfie.jpg",
    "ref_file_url": "https://example.com/accessory.jpg",
    "gender": "female",
    "style": "random"
}'

レスポンス例:

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

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

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

curl --request GET \
  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/hat/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json'

ステップ 5. 結果の取得

成功したレスポンスには、結果画像のダウンロード 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"
}

ファイル仕様とエラー

帽子バーチャル試着仕様
- 画像要件

種類	最小解像度	備考
セルフィー	512 × 512	顔が見えること、頭から胸までが推奨
帽子	512 × 512 (商品) 800 × 800 (着用時)	帽子がはっきりと、遮られずに写っていること

サポートされる帽子画像

商品画像要件
- 最小解像度: 512 × 512 ピクセル
- 画像あたり 1 つの商品のみ
- 商品は画像の高さの 25% 以上を占める必要があります

着用画像要件
- 最小解像度: 800 × 800 ピクセル
- 単一アイテム要件: モデルは正確に 1 つのアイテムのみを着用している必要があります。複数のアイテムやアクセサリーは許可されません。
- カバレッジ比率: 着用したアイテムは画像全体の height の 20% 以上を占める必要があります。これにより、アイテムがフレーム内で明確かつ目立つことが保証されます。

サポートされるセルフィービュー

推奨画像解像度: 少なくとも 512 × 512 ピクセル。
推奨顔のカバレッジ: 画像 height の 15% 以上。
単一被写体要件: 画像には正確に 1 人の人間の被写体のみが含まれている必要があります。追加の人物や部分的な人物像は許可されません。
顔の可視性: 被写体の顔が遮られることなく完全に可視である必要があります。髪、アクセサリー、またはオブジェクトが主要な顔の特徴を覆ってはいけません。
フレーミング: 画像には少なくとも頭部ショットが含まれており、頭頂部から胸までの領域をカバーする必要があります。最適な分析のためには、半身ショット（頭から腰まで）が推奨されます。

試着スタイル

バーチャル試着出力を生成するための 5 つの事前定義されたスタイルがあります: "style_sporty_casual" "style_urban_fashion" "style_vacation_casual" "style_warm_cozy" および "style_bohemian"。AI タスク作成時にこの style パラメータを指定するか、デフォルトでシステムがランダムにスタイルを選択するようにできます。

style_vacation_casual

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

AI 機能	サポートされる寸法	サポートされるファイルサイズ	サポートされる形式
帽子バーチャル試着	入力: 長辺 <= 4096 出力: 896 x 1152	< 10MB	jpg/jpeg/png/heic

エラーコード

エラーコード	説明
error_download_image	ソースまたは参照画像のダウンロードに失敗しました
error_inference	推論パイプラインエラー
error_no_face	ソース画像で顔が検出されませんでした
error_nsfw_content_detected	結果に NSFW コンテンツが検出されました
exceed_max_filesize	ファイルサイズが 10 MB を超えています
invalid_parameter	無効な gender または style 値
unknown_internal_error	その他の内部エラー

環境と依存関係

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

ユニット消費

AI 機能	消費ユニット
帽子バーチャル試着 V2.0	2

OpenAPI記述をダウンロード

ai_hat.json

ai_hat.yaml

概要

メール

YouCamOnlineEditor_API@perfectcorp.com

ライセンス

利用規約

言語

サーバー

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