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

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

基本情報

認証

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

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

X-API-Key: lc_abc12xxxxxxxxxxxxxxxxxxxxxxxx

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

共通レスポンス構造

/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 ヘッダー必須 課金: 無料（コールカウント対象外）

リクエスト

curl https://liveness.api.pas-ta.io/v1/usage \
  -H "X-API-Key: {お客様のAPIキー}"

レスポンス（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 は付与されません） 課金: 無料（コールカウント対象外）

リクエスト

curl https://liveness.api.pas-ta.io/v1/health

レスポンス（200 OK）

{"status": "ok"}

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

エラーコード一覧

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

サンプルコード

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

curl

curl には2つの書き方があります。小さい画像なら① で十分です。画像が大きくなると ① はシェルの制限に当たるため、② を使ってください。

① -d にボディを直接書く（基本形・小さい画像向け）

リクエストの形がそのまま読める、いちばん分かりやすい書き方です。

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 まで）

# 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 @-

① と ② の使い分け: Base64 文字列をコマンドライン引数へ直接展開すると（-d "{\"image\": \"$(base64 -i face.jpg)\", ...}" など）、シェルの引数長上限（ARG_MAX）に当たり argument list too long でコマンド自体が実行できなくなります。上限は環境によりますが、目安として元画像が数百 KB を超えたあたりから発生します。② の標準入力方式なら 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）し、超過課金を発生させません。ダッシュボードから切替できます。
• プラン変更: アップグレードは即時、ダウングレード・解約は翌月/月末発効です。AWS Marketplace での操作手順は プラン変更・解約 をご覧ください。
• Enterprise: 個別契約（プライベートオファー）で上限をカスタム設定します。
• 課金対象: カウントされるのは判定 API の成功応答のみです（詳細は 課金（コールカウント）について）。

バージョニング

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

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