Liveness Detection API Reference

This is the complete endpoint specification for the Liveness Detection (anti-spoofing) API (Liveness Check API). If you are using the API for the first time, please read the Quickstart Guide first.

Basic Information

Authentication

This API supports two authentication methods.

For a detection request, include the API key obtained from the dashboard (a string beginning with lc_) in the X-API-Key header.

X-API-Key: lc_abc12xxxxxxxxxxxxxxxxxxxxxxxx

The /console/* endpoints are a screen-only backend authenticated with HttpOnly cookies issued when you log in to the dashboard. They are not designed to be called directly from your programs. See Customer Dashboard for what you can do on the dashboard.

Common Response Structure

All endpoints except /v1/health return a common structure consisting of metadata and data (or error).

On success:

{
  "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": { }
}

On error:

{
  "metadata": { "...": "...", "status": "error" },
  "error": {
    "code": "invalid_image",
    "message": "No face was detected"
  }
}

metadata Fields

The monthly boundary is based on UTC. The current-month tally begins at 00:00:00 UTC on the 1st of each month, and credits expire at 23:59:59 UTC at the end of the month (consistent with the AWS Marketplace billing-month boundary).

Billing (Call Counting)

Only successful responses (status: "success") of POST /v1/check/liveness consume your monthly credits (i.e., are counted as calls). Everything else is free.

Error responses such as invalid_image, 429, and 5xx are not counted toward your monthly calls. Only successful responses that return a detection result are billable.

Detection API (/v1/*)

POST /v1/check/liveness — Liveness Detection

Send a Base64-encoded face image to determine whether it is a photo or a spoofing attack.

Authentication: X-API-Key header required Billing: Only successful responses consume 1 call (error responses are not counted)

Request

{
  "image": "<Base64-encoded image>",
  "image_format": "jpeg"
}

Response (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
  }
}

How to interpret the Processing Result: isFakeFace is a reference verdict that becomes true when isFakeLikelihood exceeds the default threshold of 0.15 (the threshold may change as detection accuracy improves; changes will be announced in the Changelog). For stricter operation, evaluate isFakeLikelihood (0.0–1.0) against a threshold on the Customer’s side. By adjusting the threshold to suit your use case, you can optimize the balance between false positives and false negatives.

Errors

GET /v1/usage — Check Current-Month Usage

Authentication: X-API-Key header required Billing: Free (not counted toward your monthly calls)

Response (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 — Health Check

Authentication: Not required (no metadata is included) Billing: Free (not counted toward your monthly calls)

{"status": "ok"}

In cases such as a DB connection failure, it returns 503 with {"status": "error", "message": "database unavailable"}.

Customer Dashboard

Account, API key, and plan settings are managed through the customer dashboard (https://liveness.api.pas-ta.io/console/dashboard). All dashboard operations are free (not counted toward your monthly calls).

The /console/* endpoints used internally by the dashboard are a screen-only backend (cookie-session authenticated). They are not designed to be called directly from your programs and may change without notice. For programmatic integration, use the Detection API (/v1/*) with X-API-Key authentication.

Sign-in and Security

• Sign-in: Email address + password, plus two-factor authentication (TOTP), which is mandatory for all accounts. On your first sign-in, scan the QR code with an authenticator app (Google Authenticator, Authy, 1Password, etc.).
• Password reset: Use “Forgot your password?” on the sign-in page and reset with the 6-digit code sent to your registered email address.

API Key Management

Each account is issued two keys, Primary and Secondary. Both work identically; keeping one as a backup enables zero-downtime rotation.

• The list shows only the leading prefix of each key (lc_abc12…). The full key is displayed only once, at the moment it is issued (account activation or regeneration). Store it in a secure location such as a password manager.
• Regenerate: Immediately invalidates the target key and issues a new one. The new key is shown once, on the spot.
• Example rotation flow: The Primary is compromised → switch to the Secondary to keep the service running → replace the key in your code → regenerate the Primary → regenerate the Secondary a few days later.

Plan, Usage, and Hard Cap

• Plan / Usage: Shows your current plan, monthly limit, and current-month usage (also available programmatically via GET /v1/usage).
• Hard cap toggle: Switch it with the button in the Plan section. ON = the API stops (429) when the limit is reached and no overage charges are incurred. OFF (default) = detection continues beyond the limit and the overage is metered. The free plan is always ON.

Plan Changes and Cancellation

Plan changes and cancellation are handled through your AWS Marketplace subscription management. Upgrades take effect immediately. Downgrades and cancellations take effect at the contract renewal timing (mid-term cancellation is not available). Please contact us if you have any questions.

Error Code List

About rate limiting: In addition to the monthly credit limit per plan, there is overall throttling (429) for fair use. This is not an individual guarantee of instantaneous rate. If you require stable high throughput, please contact us.

Sample Code

Examples of calling POST /v1/check/liveness from each language.

curl

# Pass the body via stdin (recommended). 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 @-

Why stdin? Expanding the Base64 string directly into a command-line argument, as in -d "{\"image\": \"$(base64 -i face.jpg)\", ...}", hits the shell’s argument-length limit (ARG_MAX) once the image exceeds a few hundred KB, and the command fails with argument list too long before it even runs. The stdin approach works up to the API’s 10 MB limit. tr -d '\n' is required to strip the trailing newline from the Base64 output (it would otherwise break the 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);

Plans and Usage Limits

About pricing: The table below shows AWS Marketplace public prices (USD). Private Offers are available for customers in Japan. Please contact us if interested.

• Credit system: At the start of each month, credits equal to the monthly call count are granted and expire at the end of that month (no carryover to the next month).
• Overage metering (default): Usage beyond the limit is billed on a metered basis at the overage unit price.
• Hard cap (optional, ON): When the limit is reached, the API is stopped (429) and no overage charges are incurred. You can toggle this from the dashboard.
• Plan changes: Upgrades take effect immediately; downgrades and cancellations take effect the next month / at the end of the month.
• Enterprise: The limit is set on a custom basis under an individual contract (private offer).
• Billing: Only successful detection responses are counted (see Billing (Call Counting)).

Versioning

You can check the API version in the response’s metadata.ver (semantic version, e.g., 1.0.1).

• Even after introducing /v2/, we will operate /v1/ in parallel for the time being (a deprecation notice will be given at least 6 months in advance).
• For the change history, please see the Changelog.