なりすまし判定 API クイックスタートガイド

このガイドでは、AWS Marketplace での購読から、最初のなりすまし判定リクエストを送るまでを5ステップで説明します。

項目	値
API ベース URL	`https://liveness.api.pas-ta.io`
顧客ダッシュボード	`https://liveness.api.pas-ta.io/console/dashboard`
認証方式	`X-API-Key` ヘッダー
コンテンツタイプ	`application/json`（UTF-8）

Step 1. AWS Marketplace で購読する

AWS Marketplace の なりすまし判定 API（Liveness Detection API by Swallow Incubate） 商品ページを開きます。

https://aws.amazon.com/marketplace/pp/prodview-24ciftyaakrsa
なりすまし判定 API の契約を行う AWS アカウントでサインインします。画面右上の Sign in をクリックし、AWS アカウントの認証情報を入力してください。

サインインに成功すると、画面右上に「Hello, ＜アカウント名＞」が表示された状態で商品ページに戻ります。
View purchase options をクリックしてサブスクライブ画面を開き、Auto-renewal（自動更新） の有無を選択します。

下部へスクロールし、Dimensions からプランを選択します。無料で試す場合は Free を選んでください。

Pricing details の Dimensions。プラン（Free / Starter / Standard / Professional / Business / Enterprise）を1つ選択します。

プラン	月間コール数	月額	超過単価/コール
Free（試用）	50	$0	超過不可（ハードキャップ固定）
Starter	1,000	$180	$0.18
Standard	5,000	$750	$0.15
Professional	10,000	$1,200	$0.12
Business	30,000	$2,400	$0.08
Enterprise	100,000〜（カスタム）	$5,000〜	$0.05

※ Free 以外のプランでは、上限超過時の挙動（従量課金で継続／API 停止）を後からダッシュボードで切り替えられます。
※ 日本のお客様向けには個別オファー（Private Offer）をご用意しています。ご希望の際はサポート窓口までお問い合わせください。

さらに下部へスクロールし、Terms and conditions（EULA）・Purchase order (PO) number・Purchase details を確認します。
最下部の Subscribe ボタンをクリックします。
「Your request is in progress」と表示され、契約手続きが始まります。数分で購入完了画面に切り替わります。

Step 2. アカウント情報を登録し、メールを検証する

購入完了画面の Set up your account をクリックして、当社のオンボーディング画面を開きます（Step 1-7 の手続き中の画面からでも開けます）。

お客様の AWS Account ID と Subscription ID が自動表示された登録画面に遷移します。次の項目を入力して Continue をクリックしてください。

オンボーディングの登録画面。AWS Account ID と Subscription ID は自動入力されます。

項目	必須	備考
First name / Last name	必須	ご担当者名
業務用メールアドレス（Work email）	必須	ログイン ID と各種通知の宛先になります
会社名（Company name）	必須
会社ホームページ URL（Company website）	必須	`https://example.com` の形式

登録したメールアドレスに 検証リンク（有効期限24時間） が送信されます。

届いたメール本文の URL をクリックしてください。

メールが届かない場合は、迷惑メールフォルダをご確認ください。送信元は noreply@liveness.api.pas-ta.io です。

Step 3. パスワードを設定し、API キーを控える

検証リンクからパスワード設定画面に進みます。8文字以上・大文字・小文字・数字・記号を各1文字以上含むパスワードを設定し、Activate account をクリックします。
アカウントが有効化され、Primary / Secondary の2つの API キーが表示されます。両方とも必ず控えてから Go to console をクリックしてください。

⚠️ API キーの全文が表示されるのはこの画面だけです。 この画面を離れると全文は二度と表示されません（ダッシュボードでは lc_a1B2c… のような先頭プレフィックスのみ表示されます）。パスワードマネージャー等に保存してください。

控え忘れた場合は、ダッシュボードの Regenerate で新しいキーを発行してください（旧キーは即時無効化され、新キーはその場で1回だけ表示されます）。

2キー運用について: 通常は Primary キーを使用します。万一キーが漏れた場合は、Secondary を使いながらコードを差し替え、Primary を再生成することで無停止でローテーションできます。

Step 4. コンソールにログインし、2段階認証を設定する

ログイン画面で、Step 2 で登録したメールアドレスと Step 3 で設定したパスワードを入力し、Sign in をクリックします。
2段階認証（TOTP）の設定画面になります。Google Authenticator・Authy・1Password などの認証アプリで QR コードを読み取り、表示された6桁のワンタイムパスワードを入力して Verify and enable をクリックします。

2段階認証の設定は必須です。QR コードを読み取れない場合は、「Or enter this secret manually」に表示された文字列を認証アプリに手入力してください。
設定が完了すると顧客ダッシュボードにログインできます。プラン・当月の使用量・API キーの状態を確認できます。
登録完了メールが届きます。以後は次の URL からログインしてください。

https://liveness.api.pas-ta.io/console/dashboard

Step 5. 最初の判定リクエストを送る

顔画像を Base64 エンコードして POST /v1/check/liveness に送信します。

① 基本形（小さい画像向け）

curl -X POST https://liveness.api.pas-ta.io/v1/check/liveness \
  -H "X-API-Key: {お客様のAPIキー}" \
  -H "Content-Type: application/json" \
  -d '{"image": "{Base64エンコードされた画像}", "image_format": "jpeg"}'

② 大きい画像向け（10MB まで）

# 画像を Base64 化し、標準入力からボディを渡して送信（macOS は base64 -i / Linux は base64 -w0）
{ printf '{"image": "'; base64 -i face.jpg | tr -d '\n'; printf '", "image_format": "jpeg"}'; } \
| curl -X POST https://liveness.api.pas-ta.io/v1/check/liveness \
  -H "X-API-Key: {お客様のAPIキー}" \
  -H "Content-Type: application/json" \
  --data-binary @-

①で argument list too long が出たら②へ: Base64 文字列を引数に直接展開すると、シェルの引数長上限（目安として元画像が数百 KB を超えたあたり）でコマンド自体が実行できなくなります。②の標準入力方式なら API 上限の 10MB まで送信できます（tr -d '\n' は JSON 破損防止に必要）。

フィールド	必須	説明
`image`	○	Base64 エンコードした画像（上限 10MB）
`image_format`	○	`"jpeg"` または `"png"`

レスポンス例（200 OK）:

{
  "metadata": {
    "ver": "1.0.1",
    "customer_id": "550e8400-e29b-41d4-a716-446655440000",
    "remaining_calls": 3850,
    "over_limit_calls": 0,
    "status": "success"
  },
  "data": {
    "isFakeFace": false,
    "isFakeLikelihood": 0.987,
    "isValidFace": true,
    "faceBrightness": 142.3,
    "latency_ms": 120
  }
}

判定結果の読み方: isFakeFace（true＝写真・なりすまし疑い）は、isFakeLikelihood（0.0〜1.0 のスコア）が既定しきい値 0.15 を上回ると true になる参考判定です。より厳密な運用では isFakeLikelihood をお客様側のしきい値で評価してください。

課金について: コールとしてカウントされるのは判定の成功応答のみです。エラー応答（4xx/5xx）や GET /v1/usage・GET /v1/health・ダッシュボード操作はカウントされません。

次のステップ

使用量の確認: GET /v1/usage（当月のコール数・残クレジット・プランを返します）
よくあるエラー: 401 invalid_api_key（キー不正）/ 400 invalid_image（顔未検出・壊れた画像）/ 429 quota_exceeded（上限到達かつ停止設定時）→ 詳細は FAQ をご覧ください
レート制限: プランごとの月間クレジット上限に加え、公正利用のための全体スロットリング（429）があります。これは瞬間レートの個別保証ではありません。
画面での管理: API キーの再生成・プラン・使用量の確認は顧客管理画面ガイドをご覧ください
お困りのとき: サポート窓口（なりすまし判定 API について: liveness-api@swallow-incubate.com）