エンドポイント概要

どんな機能か。 お客様の商品カタログを、精密な肌分析とマッチングします。販売しているスキンケア商品を説明とともにアップロードし、カタログの id を渡すと、エンドポイントが検出された肌悩みごとに最も適した商品を llm_results.json で返します。

一般的な LLM レコメンドとの違いは、入力です。一般的な LLM は確率と事前知識にもとづいて推奨します。Perfect の AI 肌分析は、まず科学的で定量化された肌指標と実際の検出マスクを生成するため、モデルは実測された肌状態をもとに商品をマッチングします — 信頼性が高く、高速で、説明可能。統計的な推測ではありません。

パラメータ

フィールド	型	必須	デフォルト	説明
`catalog_id`	文字列	はい	—	商品カタログのアップロードで取得します。`ready` 状態で、お客様のアカウントに属している必要があります。
`top_n`	整数	いいえ	`3`	肌悩みごとに推奨する商品数。最小 `1`。カタログの `sku_count` を超えないこと。

前提条件 — 商品カタログをアップロードする

商品カタログは、AI 肌分析がレコメンドの元にする商品のリストです。1 度アップロードして catalog_id を保管すれば、分析の呼び出しごとにその id を渡すだけです。カタログは個々の API キーではなくお客様のアカウントに属します。プロジェクトキーを含め、アカウントのすべての API キーが同じカタログを参照し、キーのローテートや削除の影響も受けません。カタログのアップロードと保存は無料です。

カタログファイルの要件

項目	値
形式	ヘッダー行付きの CSV
エンコーディング	UTF-8（BOM の有無は問いません。Excel の「CSV UTF-8」形式では BOM が付与されます）
ファイルサイズの上限	5 MB
SKU 数の上限	ファイルサイズの上限以外にはありません
必須の列	`product_id`、`product_name`、`product_description`

追加の列は無視されますが、5 MB の上限にはカウントされます。カンマや改行を含む値はクォートで囲んでください。空でないデータ行は 1 行につき 1 SKU としてカウントされます。

product_id,product_name,product_description
SKU-001,Hydrating Serum,"A lightweight serum for dry skin."
SKU-002,Brightening Cream,"Evens out skin tone, for daily use."
SKU-003,Barrier Repair Cream,"Rich cream for dry, redness-prone skin."

# Upload a catalog — validated in the same request
curl -sS -X POST "$BASE_URL/s2s/v2.1/product-catalog" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@catalog.csv" \
  -F "name=Summer skincare"

有効なファイルを送信すると status: ready とともに catalog_id と sku_count が返されます — その id を保管してください:

{
  "status": 200,
  "data": {
    "catalog_id": "1662043585118399001",
    "name": "Summer skincare",
    "status": "ready",
    "created_time": 1760256000000,
    "sku_count": 3
  }
}

# List every catalog of your account, newest first (ready and failed alike)
curl -sS -H "Authorization: Bearer $API_KEY" "$BASE_URL/s2s/v2.1/product-catalog"

# Delete a catalog — immediate and permanent
curl -sS -X DELETE -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/s2s/v2.1/product-catalog/1662043585118399001"

カタログの状態と制限

ステータス	意味	肌分析で使用可能
`ready`	アップロードと検証が完了	可
`failed`	アップロードされたが、ファイルの検証に失敗	不可

検証に失敗したアップロードはエラーを返しますが、failed 状態のカタログとして記録され、カタログ一覧 (List catalogs) に表示されます。エラー本文にその catalog_id が載ることはありません。1 つのアカウントで保持できるカタログは、ready と failed を合わせて最大 10 件です — 新しくアップロードする前に 1 件削除してください。カタログを更新するには新しいファイルをアップロードします。アップロードごとに新しい catalog_id が作成され、旧カタログは削除するまで引き続き使用できるため、新しいカタログを確認してから切り替えることができます。

AI タスクを作成する

# Skin Analysis with Product Recommendation
curl -sS -X POST "$BASE_URL/s2s/v2.1/task/skin-analysis-recommendation" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "src_file_url": "https://your-cdn.example.com/customer-001.jpg",
    "dst_actions": [
      "hd_skin_type", "hd_wrinkle", "hd_pore", "hd_texture",
      "hd_acne", "hd_redness", "hd_oiliness", "hd_moisture",
      "hd_age_spot", "hd_radiance", "hd_dark_circle"
    ],
    "format": "zip",
    "pf_camera_kit": true,
    "product_recommendation": {
      "catalog_id": "1662043585118399001",
      "top_n": 3
    }
  }'

検証。 以下のいずれの場合も error_code: InvalidParameters を伴う 400 が返され、課金は発生しません:

原因	`error` メッセージ
`product_recommendation` を指定したのに `catalog_id` がない	`catalog_id is required when product_recommendation is provided.`
カタログが存在しない、削除済み、または他のアカウントの所有	`No catalog was found with this catalog_id.`
アップロード時の検証に失敗したカタログ（`status: failed`）	`This catalog failed validation when it was uploaded and can't be used. Upload the catalog again.`
`top_n` が 1 以上の整数ではない	(よくある `InvalidParameters` のケース)
`top_n` がカタログの商品数を超えている	`product_recommendation.top_n can't be more than the 3 products in this catalog.`

最後のメッセージは動的で、カタログの実際の sku_count が表示されます。カタログ一覧 (List catalogs) から sku_count を読み取り、クライアント側で top_n がその値以下に収まるよう調整してください。

レポートとレコメンドをポーリングする

実行のたびに BasicRunTaskResponseV2 がただちに返されます。返された id でタスクをポーリングしてください。レポートとレコメンドは llm_results.json に届けられます。

# 1. Run the task and capture the task id
TASK_ID=$(curl -sS -X POST "$BASE_URL/s2s/v2.1/task/skin-analysis-recommendation" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }' | jq -r '.data.task_id')

# 2. Poll until task_status is "success"
curl -sS -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/s2s/v2.1/task/skin-analysis-recommendation/$TASK_ID"

task_status は running → success | error と遷移します。format: zip の場合、results.url は 2 時間有効なダウンロードリンクで、ZIP には score_info.json とすべての検出画像を収めた skinanalysisResult フォルダが入っています。format: json の場合、results.output にスコアがレスポンス本文へ直接返されます。

リクエストフィールド早見表

フィールド	必須	説明
`src_file_id` / `src_file_url`	はい（いずれか 1 つ）	入力画像。`BasicRunTaskV2` に準拠
`dst_actions`	はい	HD 機能または SD 機能 — 混在は不可
`format`	いいえ	`zip`（デフォルト）\| `json` — レスポンススキーマが異なります
`pf_camera_kit`	いいえ	V2.1 で追加。顔の輪郭と各顔部位の位置特定
`miniserver_args`	いいえ	マスクオーバーレイと HD 毛穴・しわの背景の制御
`advanced_report`	いいえ	指定 → レポートを出力。`{}` → すべてデフォルト値。省略 → なし
`product_recommendation`	いいえ	指定 → レコメンドを出力。`catalog_id` が必要

解像度。 すべての出力画像は長辺 2560 px までに上限設定され、入力は自動的にリサイズされます。enable_mask_overlay が false の場合、生のマスクが .png で返されるため、合成はお客様側で行う必要があります — 入力解像度を確認し、長辺が 2560 px を超える場合は表示サイズを 2560 px 基準で設計してください。