Liveness Detection API — FAQ & Troubleshooting

This page summarizes frequently asked questions and how to resolve errors when they occur. For how to use the API, see the Quickstart Guide; for details on each endpoint, see the API Reference.

Basics

What does the Liveness Detection API determine?

It determines whether a submitted facial image is a real, live face or a fake (a spoofing attempt) such as a face shown in a photo or on a smartphone screen. The result is returned via isFakeFace (whether the image is suspected to be fake) and isFakeLikelihood (a score from 0.0 to 1.0). It does not perform identity verification (face recognition) itself.

Do you also provide face recognition or eKYC?

No. This API provides the core technology for “liveness detection (anti-spoofing),” which is used in combination before or after face recognition. Please prepare your own face recognition engine or eKYC service on your side and use it together with this API.

Does it support video or action-based detection (detecting an instructed motion)?

This API (POST /v1/check/liveness) supports fake-image detection based on a single still image. If you need video-based action detection, please consider using the SDK (please contact us).

Can I use images taken with a smartphone camera?

Yes. No special camera is required; you can use images captured with a smartphone’s built-in camera.

Authentication & API Keys

I receive 401 invalid_api_key

Please check the following points:

• Whether the full key (a string beginning with lc_) is correctly set in the X-API-Key header
• Whether the key has been deactivated or regenerated (regenerating immediately invalidates the old key)
• Whether the key is valid on the “API Keys” screen of the dashboard

Where do I obtain an API key?

The two keys, Primary and Secondary, are displayed in full on the screen right after account activation (this is the only time the full keys are shown). If you did not save them, issue a new key with Regenerate on the customer dashboard (https://liveness.api.pas-ta.io/console/dashboard); the old key is invalidated immediately, and the new key is shown once, on the spot.

What should I do if my key is leaked?

You can regenerate the Primary key while continuing your service by switching to the Secondary key (zero-downtime rotation). For the procedure, see the Quickstart Guide.

Requests & Images

I receive 400 invalid_image

This occurs when the image fails to decode or when no face can be detected.

• The only supported formats are jpeg and png, and the maximum size is 10 MB
• Make sure that image_format matches the actual image format
• Make sure the face is facing forward and is captured with sufficient brightness and resolution (→ Image Input Guidelines)

I receive 400 invalid_request

This is a format error in the request body. Please make sure that image (a Base64 string) and image_format (either "jpeg" or "png") are correctly included.

How should I send the image?

Base64-encode the image and send it to POST /v1/check/liveness as JSON in the form {"image": "...", "image_format": "jpeg"}. For sample code (curl / Python / Node.js), see the API Reference.

Rate Limits & Usage

I receive 429 quota_exceeded

This occurs when the monthly call limit has been reached and the API is in stop mode.

• You can check the current month’s usage with GET /v1/usage
• To continue using the API, either turn the hard cap OFF in the dashboard (continue with overage billing) or upgrade to a higher plan
• The free plan does not support overage billing, so it always returns 429 when the limit is reached

What happens when I exceed the limit?

By default (hard cap OFF), processing continues even after the limit is exceeded, and the overage is billed on a usage basis. When the hard cap is ON, the API stops at the limit (429). You can switch this behavior at any time from the dashboard.

Can credits be carried over to the next month?

No. Credits granted at the beginning of the month are valid for that month only and are not carried over to the next month (monthly boundaries are based on UTC).

Interpreting the Processing Result

How do I make the final “spoofing or not” determination?

Evaluate isFakeFace (true = suspected fake) and isFakeLikelihood (a score from 0.0 to 1.0) against a threshold suited to your use case. The API does not return a fixed pass/fail (result). By adjusting the threshold, you can optimize the balance between false positives and false negatives.

Why doesn’t the response include the analyzed image?

To keep the response size small, no image data is returned. Only the numerical values needed for the determination (isFakeFace / isFakeLikelihood, the face bounding box, etc.) are returned.

Performance & Operations

How long does a single determination take?

The inference itself takes roughly a few hundred milliseconds (you can check this with latency_ms in the response). The actual response time, including the network round trip, varies depending on your environment and the image size.

Which programming languages and operating systems are supported?

You can use the API in any language or operating system, as long as your environment can send requests over HTTPS. For sample code (curl / Python / Node.js), see the API Reference.

I receive 503 service_unavailable

The service is temporarily unavailable. Please wait a little while and try again. If the issue persists, please contact us.

If you cannot find the information you are looking for, please contact us via the inquiry form.