技術ドキュメント

概要

VTO API Serviceは、HMAC署名とJWTトークンを組み合わせた2段階の認証フローを採用しています。 まずサーバー側でHMAC署名を生成し、トークンエンドポイントからJWTを取得。その後、JWTを用いてWidgetを認証し、 VTOやステータス取得を行います。

ステップ1: HMAC署名の生成（サーバー側）

// 署名対象文字列: api_key|origin|timestamp（パイプ区切り）
message   = "api_XXXX-XXXX-XXXX-XXXX|https://your-ec-site.com|1710345600"
signature = hmac_sha256(message, shared_secret)

// PHP例:
$message   = $apiKey . '|' . $origin . '|' . $timestamp;
$signature = hash_hmac('sha256', $message, $sharedSecret);

パラメータ:

• api_key: マイページで取得したAPIキー（api_XXXX-XXXX-XXXX-XXXX）
• origin: ECサイトのオリジン（例: https://your-ec-site.com）
• timestamp: 現在のUnixタイムスタンプ（秒）※ ±5分以内
• shared_secret: マイページで確認できるシークレットキー

ステップ2: JWTトークンの取得

POST /API/api/token.php
Content-Type: application/json

{
    "api_key": "api_XXXX-XXXX-XXXX-XXXX",
    "origin": "https://your-ec-site.com",
    "timestamp": 1710345600,
    "signature": "hmac_sha256_hex_string"
}

レスポンス:

{
    "success": true,
    "data": {
        "widget_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "expires_in": 3600
    }
}

ステップ3: Widgetの初期化

取得した widget_token は Widget JS が自動で使用します。
お客様サーバーにプロキシPHPを設置し、Widget JS の tokenEndpoint に指定してください。

<script src="https://asp.kitemir.jp/API_SERVICES/widget/vto-widget.js"></script>
<link rel="stylesheet" href="https://asp.kitemir.jp/API_SERVICES/widget/vto-widget.css">
<script>
VtoWidget.init({
    tokenEndpoint: '/api/widget_token.php',  // お客様サーバーのプロキシPHP
    apiBase: 'https://asp.kitemir.jp/API_SERVICES'
});
</script>

<!-- 商品ページに試着ボタンを設置 -->
<button onclick="VtoWidget.open({
    garmentUrl: 'https://your-ec-site.com/images/product.webp',
    category: 'tops',
    productName: 'エレガントブラウス',
    productPrice: 12000,
    onAddToCart: function() { addToMyCart(123); }
})">試着してみる</button>

例1: トークン取得（サーバー側プロキシから呼び出し）

リクエスト:

curl -X POST https://asp.kitemir.jp/API/api/token.php \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "api_1234-5678-9abc-def0",
    "origin": "https://your-ec-site.com",
    "timestamp": 1710345600,
    "signature": "a1b2c3d4e5f6..."
  }'

レスポンス（成功）:

{
    "success": true,
    "data": {
        "widget_token": "eyJhbGciOiJIUzI1NiIs...",
        "expires_in": 3600
    }
}

例2: VTO実行

multipart/form-data 方式:

curl -X POST https://asp.kitemir.jp/API/api/tryon.php \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -F "person_image=@person.jpg" \
  -F "garment_url=https://your-ec-site.com/images/dress.webp" \
  -F "category=one-pieces"

JSON方式（base64）:

curl -X POST https://asp.kitemir.jp/API/api/tryon.php \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "person_image": "/9j/4AAQSkZJRg...(base64)",
    "garment_url": "https://your-ec-site.com/images/dress.webp",
    "category": "one-pieces"
  }'

レスポンス（成功）:

{
    "success": true,
    "data": {
        "tryon_id": "pred_abc123def456",
        "status": "processing"
    }
}

例3: VTOステータス確認（完了時）

リクエスト:

curl -X GET "https://asp.kitemir.jp/API/api/status.php?tryon_id=vto_1710345678_abc123" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

レスポンス（完了）:

{
    "success": true,
    "data": {
        "status": "completed",
        "result_url": "https://cdn.fashn.ai/results/tryon_123456.jpg",
        "designer_comment": "このワンピースはあなたの優雅さを引き出しており、非常に素敵です。深い色合いは肌のトーンを美しく見せ、シルエットは体を的確にサポートしています。特に首周りのデザインは顔立ちを柔らかく見せています。",
        "cost_usd": 0.075
    }
}