エンドポイント概要

どんな機能か。 詳細肌レポートと商品レコメンドを備えた AI 肌分析を、1 回の呼び出しで。実測された肌指標とプロフェッショナルなスキンケア参照データベースに基づく高精度なレポートと、お客様の商品のみから選ばれたレコメンドを、1 回のリクエスト・1 本のポーリングフローで取得できます。

これが、1 回の API 呼び出しで完結するサイクルです。科学的で信頼性の高い精密な肌分析レポートと、お客様のカタログのみに基づく商品レコメンドを一度に提供します。商品の露出とユーザー定着を、途切れない 1 つのユーザージャーニーの中で同時に実現します。

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

商品カタログは、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 Intel System — Report + Recommendations
curl -sS -X POST "$BASE_URL/s2s/v2.1/task/skin-analysis-report-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", "hd_firmness",
      "hd_eye_bag", "hd_tear_trough", "hd_droopy_upper_eyelid",
      "hd_droopy_lower_eyelid"
    ],
    "format": "zip",
    "pf_camera_kit": true,
    "miniserver_args": {
      "enable_mask_overlay": true
    },
    "advanced_report": {
      "language": "enu",
      "tone": "warm",
      "country": "United States",
      "city": "New York"
    },
    "product_recommendation": {
      "catalog_id": "1662043585118399001",
      "top_n": 3
    }
  }'

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

実行のたびに 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-report-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-report-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 基準で設計してください。