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 the Customer Console Guide for what you can do on the screens, including sign-in, API key management, and plan settings.

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)

Request

curl https://liveness.api.pas-ta.io/v1/usage \
  -H "X-API-Key: {your API key}"

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)

Request

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

Response (200 OK)

{"status": "ok"}

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

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 Support.

Sample Code

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

curl

There are two ways to write this with curl. For small images, ① is all you need. As the image grows, ① hits a shell limit, so use ② instead.

① Put the body directly in -d (basic form, for small images)

This is the most readable form — the shape of the request is visible at a glance.

curl -X POST https://liveness.api.pas-ta.io/v1/check/liveness \
  -H "X-API-Key: {your API key}" \
  -H "Content-Type: application/json" \
  -d '{"image": "{Base64-encoded image}", "image_format": "jpeg"}'

② Pass the body via stdin (for large images, up to 10 MB)

# 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: {your API key}" \
  -H "Content-Type: application/json" \
  --data-binary @-

Choosing between ① and ②: 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), and the command fails with argument list too long before it even runs. The limit depends on your environment, but as a rule of thumb this starts happening once the source image exceeds a few hundred KB. The stdin approach in ② 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 Support 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. For the procedure in AWS Marketplace, see Plan changes and cancellation.
• 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.