AI ネックレスバーチャル試着
ネックレスのバーチャル試着を作成します。 AI の首元と鎖骨トラッキングにより、ネックレスの試着プレビューを生成します。
2D 画像からネックレスのバーチャル試着を作成します。3D モデリングは不要です。
本ガイドでは以下内容を説明します:
- エンドポイント:
/s2s/v2.0/task/2d-vto/necklace - 認証: すべてのリクエストに
Authorization: Bearer YOUR_API_KEYが必要です - ワークフロー:
- セルフィー画像を準備する: 画像をアップロードするか、有効な画像 URL を提供します
- ネックレス画像を準備する: 画像をアップロードするか、ネックレス製品の有効な画像 URL を提供します
- AI タスクを発行しタスク ID を取得する: レスポンスから
task_idを取得します。 - ステータスをポーリングする（
GET）:task_idを使用してタスクのステータスを確認します。task_statusが"success"または"error"になるまでポーリングを続行してください。
- API プレイグラウンド
API プレイグラウンドで API を対話的にテストします:
- 認証
- リクエストヘッダーに Bearer Token を使用して API キーを含めます:
Authorization: Bearer YOUR_API_KEY
API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/.
- 画像のアップロード
ファイルをサーバーに直接アップロードするか、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）のオクルージョンマスク画像ファイルを提供してセグメンテーションを微調整できます。
- ネックレス VTO タスクの作成と結果のポーリング
画像とテンプレート ID が揃ったら、タスクを作成します。API はリクエストを非同期で処理します。ステータスが success または error に達するまでタスクステータスをポーリングする必要があります。
- タスク作成エンドポイント
POST /s2s/v2.0/task/2d-vto/necklace- ポーリングエンドポイント
GET /s2s/v2.0/task/2d-vto/necklace/{task_id}- ネックレスバーチャル試着の仕様
サポートされるネックレスビュー 背景を除去した、ネックレスを着用した前面画像。
サポートされるセルフィービュー 首が明確に見えており、遮蔽のない前面のセルフィー。頭の水平回転は 20 度以内でサポートされます。頭のサイズは比例したものであり、首の幅は画像幅の少なくとも 15 パーセントを占める必要があります。
necklace_wearing_location: array of two points (optional) ネックレスを配置すべき写真内のターゲット位置を指定します。 デフォルト: null（エンジンのデフォルト）
necklace_shadow_intensity: float (0.0 to 1.0) 影の強さを制御します: 0.0 は影なしを示します 1.0 は最大限の影を示します デフォルト値: 0.15
necklace_ambient_light_intensity: float (0.0 to 1.0) ライティングがセルフィー画像を参照する度合いを定義します: 0.0 はセルフィー画像のライティングを無視します 1.0 はセルフィー画像のライティングと影のレンダリングに完全に一致させます デフォルト値: 1.0
ネックレスアンカーポイント: ピクセル座標の 2 点の配列（任意） 製品画像内のネックレスチェーンの左右に見える端部のアンカーポイントを指定し、アラインメントに使用します。 デフォルト: null（エンジンのデフォルト）
- サポートされる形式と寸法
| 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 |