なりすまし判定 API リファレンス

なりすまし判定 API（Liveness Check API）の全エンドポイント仕様です。はじめてご利用の方は、先に クイックスタートガイド をご覧ください。

基本情報

認証

本 API には2種類の認証方式があります。

判定リクエストには、ダッシュボードで取得した API キー（lc_ で始まる文字列）を X-API-Key ヘッダーに付与します。

X-API-Key: lc_abc12xxxxxxxxxxxxxxxxxxxxxxxx

/console/* は、ダッシュボードへのログインで発行される HttpOnly Cookie で認証される画面専用のバックエンドです。プログラムから直接呼び出す用途には設計されていません。ダッシュボードでできることは 顧客ダッシュボード をご覧ください。

共通レスポンス構造

/v1/health を除くすべてのエンドポイントは、metadata と data（または error）からなる共通構造を返します。

成功時:

{
  "metadata": {
    "date": "2026-05-04T12:34:56.789Z",
    "ver": "1.0.1",
    "customer_id": "550e8400-e29b-41d4-a716-446655440000",
    "remaining_calls": 3850,
    "over_limit_calls": 0,
    "status": "success"
  },
  "data": { }
}

エラー時:

{
  "metadata": { "...": "...", "status": "error" },
  "error": {
    "code": "invalid_image",
    "message": "顔が検出できませんでした"
  }
}

metadata フィールド

月次境界は UTC 基準です。毎月 1 日 00:00:00 UTC に当月集計が始まり、月末 23:59:59 UTC でクレジットが消滅します（AWS Marketplace の課金月境界と一致）。

課金（コールカウント）について

月間クレジットを消費する（= コールとしてカウントされる）のは、POST /v1/check/liveness の成功応答（status: "success"）のみです。それ以外はすべて無料です。

画像不備（invalid_image）・上限超過（429）・サーバーエラー（5xx）などのエラー応答は月間コール数にカウントされません。判定結果をお返しできた成功応答だけが課金対象です。

判定 API（/v1/*）

POST /v1/check/liveness — なりすまし判定

顔画像を Base64 エンコードして送信し、写真・なりすまし攻撃かどうかを判定します。

認証: X-API-Key ヘッダー必須 課金: 成功応答のみ1コール消費（エラー応答はカウントされません）

リクエスト

{
  "image": "<Base64エンコード画像>",
  "image_format": "jpeg"
}

レスポンス（200 OK）

{
  "metadata": {
    "date": "2026-05-04T12:34:56.789Z",
    "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,
    "faceRectArea": {"x": 120, "y": 80, "width": 200, "height": 200},
    "vFaceRect": [
      {"x": 120, "y": 80, "width": 200, "height": 200}
    ],
    "msg": "",
    "latency_ms": 120
  }
}

判定結果の読み方: isFakeFace は、isFakeLikelihood が既定のしきい値 0.15 を上回った場合に true となる参考判定です（しきい値は精度改善に伴い変更されることがあります。変更時は Changelog でお知らせします）。より厳密な運用では、isFakeLikelihood（0.0〜1.0）をお客様側のしきい値で評価してください。しきい値を用途に応じて調整することで、誤検知（False Positive）と見逃し（False Negative）のバランスを最適化できます。

エラー

GET /v1/usage — 当月使用量の確認

認証: X-API-Key ヘッダー必須 課金: 無料（コールカウント対象外）

レスポンス（200 OK）

{
  "metadata": { "...": "...", "status": "success" },
  "data": {
    "year_month": "2026-05",
    "total_calls": 1150,
    "monthly_limit": 5000,
    "remaining_calls": 3850,
    "over_limit_calls": 0,
    "plan": "standard",
    "hard_cap_enabled": false
  }
}

GET /v1/health — ヘルスチェック

認証: 不要（metadata は付与されません） 課金: 無料（コールカウント対象外）

{"status": "ok"}

DB 接続失敗などの場合は 503 で {"status": "error", "message": "database unavailable"} を返します。

顧客ダッシュボード

アカウント・API キー・プラン設定の管理は、顧客ダッシュボード（https://liveness.api.pas-ta.io/console/dashboard）の画面操作で行います。ダッシュボードの操作はすべて無料（コールカウント対象外）です。

ダッシュボードが内部的に使用する /console/* エンドポイントは画面専用のバックエンド（Cookie セッション認証）であり、プログラムから直接呼び出す用途には設計されていません。予告なく変更されることがあります。プログラム連携には X-API-Key 認証の判定 API（/v1/*）をご利用ください。

ログインとセキュリティ

• ログイン: メールアドレス + パスワードに加え、2要素認証（TOTP）が全アカウントで必須です。初回ログイン時に認証アプリ（Google Authenticator / Authy / 1Password など）で QR コードを読み取ってセットアップします。
• パスワードリセット: ログイン画面の「Forgot your password?」から。登録メールアドレスに届く6桁コードで再設定します。

API キー管理

各アカウントには Primary / Secondary の2キーが発行されます。両キーは同等に機能し、片方を予備として保持することで無停止ローテーションができます。

• 一覧にはキーの先頭プレフィックス（lc_abc12…）のみが表示されます。キー全文が表示されるのは発行された瞬間（アカウント有効化時・再生成時）の1回だけです。パスワードマネージャなどの安全な場所に保管してください。
• Regenerate: 対象キーを即時無効化し、新しいキーを発行します。新キーはその場で1回だけ表示されます。
• ローテーション手順の例: Primary が漏洩 → Secondary に切り替えてサービス継続 → コードを差し替え → Primary を Regenerate → 数日後に Secondary も Regenerate。

プラン・使用量・ハードキャップ

• Plan / Usage: 現在のプラン・月間上限・当月の使用状況を表示します（プログラムからは GET /v1/usage でも取得できます）。
• ハードキャップ切替: Plan セクションのボタンで切り替えます。ON = 上限到達で API を停止（429）し超過課金なし / OFF（既定） = 上限超過後も判定を継続し超過分を従量課金。free プランは常時 ON 固定です。

プラン変更・解約

プランの変更・解約は AWS Marketplace の購読管理から行います。アップグレード（上位プランへの変更）は即時反映されます。ダウングレード・解約は契約更新のタイミングでの反映となります（途中解約はできません）。ご不明な点はお問い合わせください。

エラーコード一覧

レート制限について: プランごとの月間クレジット上限に加え、公正利用のための全体スロットリング（429）があります。これは瞬間レートの個別保証ではありません。安定した高スループットが必要な場合はお問い合わせください。

サンプルコード

POST /v1/check/liveness を各言語から呼び出す例です。

curl

# 標準入力からボディを渡す方式（推奨）。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: lc_abc12xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  --data-binary @-

なぜ標準入力方式か: -d "{\"image\": \"$(base64 -i face.jpg)\", ...}" のように Base64 文字列をコマンドライン引数へ直接展開すると、画像が数百 KB を超えたあたりでシェルの引数長上限（ARG_MAX）に達し、argument list too long エラーでコマンド自体が実行できません。標準入力方式なら API の上限（10MB）まで送信できます。tr -d '\n' は Base64 出力末尾の改行除去（JSON 破損防止）に必要です。

Python

import base64
import requests

with open("face.jpg", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode("ascii")

resp = requests.post(
    "https://liveness.api.pas-ta.io/v1/check/liveness",
    headers={"X-API-Key": "lc_abc12xxxxxxxxxxxxxxxxxxxxxxxx"},
    json={"image": image_b64, "image_format": "jpeg"},
    timeout=30,
)
resp.raise_for_status()
result = resp.json()["data"]
print("fake?", result["isFakeFace"], "likelihood:", result["isFakeLikelihood"])

Node.js

import { readFileSync } from "node:fs";

const imageB64 = readFileSync("face.jpg").toString("base64");

const resp = await fetch("https://liveness.api.pas-ta.io/v1/check/liveness", {
  method: "POST",
  headers: {
    "X-API-Key": "lc_abc12xxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ image: imageB64, image_format: "jpeg" }),
});

const { data } = await resp.json();
console.log("fake?", data.isFakeFace, "likelihood:", data.isFakeLikelihood);

プランと使用量上限

価格について: 下表は AWS Marketplace 公開価格（USD）です。日本のお客様向けには個別オファー（Private Offer）をご用意しています。 ご希望の際はお問い合わせください。

• クレジット制: 月初に月間コール数分のクレジットが付与され、当月限りで消滅します（翌月繰越なし）。
• 超過従量（デフォルト）: 上限を超えた分は超過単価で従量課金されます。
• ハードキャップ（任意で ON）: 上限到達で API を停止（429）し、超過課金を発生させません。ダッシュボードから切替できます。
• プラン変更: アップグレードは即時、ダウングレード・解約は翌月/月末発効です。
• Enterprise: 個別契約（プライベートオファー）で上限をカスタム設定します。
• 課金対象: カウントされるのは判定 API の成功応答のみです（詳細は 課金（コールカウント）について）。

バージョニング

API のバージョンは、レスポンスの metadata.ver（セマンティックバージョン・例 1.0.1）で確認できます。

• /v2/ を新設しても、当面は /v1/ を並行運用します（廃止予告は最低6ヶ月前）。
• 変更履歴は Changelog をご覧ください。