Liveness Detection

Perform passive liveness detection to verify whether a face image belongs to a real, live person.
This service detects spoof attempts such as printed photos, screen replays, masks, or AI-generated faces using anti-spoofing analysis.

POST

/api/gw/services/liveness

---

Authorizations

x-api-key · string · required

API key used to authenticate the request.

---

Body

faceImageBase64 · string · required

Base64-encoded face image used for liveness detection.

faceImageFileName · string

Original filename of the uploaded image.

faceImageBytes · string

Optional raw image bytes instead of Base64 input.

---

Response

200

success · boolean

Indicates whether the request was processed successfully.

requestId · string

Unique identifier for the API request.

correlationId · string

Identifier used for tracing the request across systems.

data · object

Contains liveness detection results.

data.isLive · boolean

Indicates whether the subject is detected as a live person.

data.confidenceScore · number

Confidence score of the liveness prediction (may be null).

data.livenessStatus · string

Overall liveness decision status (e.g., Approved, Declined).

error · object | null

Contains error details if the request fails; otherwise null.

durationMs · number

Time taken to process the request in milliseconds.

processedAt · string

Timestamp when the request was processed (ISO 8601 format).

400

error · string

Error message describing why the request failed.

code · string

Machine-readable error code for debugging.

---

Curl

curl -X POST "https://dev-idf-gw.cognetlabs.org/api/gw/services/liveness" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "faceImageBase64": "<base64-face>",
    "faceImageFileName": "selfie.jpg"
  }'

import requests

url = "https://dev-idf-gw.cognetlabs.org/api/gw/services/liveness"

headers = {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
}

payload = {
    "faceImageBase64": "<base64-face>",
    "faceImageFileName": "selfie.jpg"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

fetch("https://dev-idf-gw.cognetlabs.org/api/gw/services/liveness", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
  },
  body: JSON.stringify({
    faceImageBase64: "<base64-face>",
    faceImageFileName: "selfie.jpg"
  })
})
.then(res => res.json())
.then(console.log);

<?php
$url = "https://dev-idf-gw.cognetlabs.org/api/gw/services/liveness";

$data = [
  "faceImageBase64" => "<base64-face>",
  "faceImageFileName" => "selfie.jpg"
];

$options = [
  "http" => [
    "header"  => "Content-Type: application/json\r\nx-api-key: YOUR_API_KEY",
    "method"  => "POST",
    "content" => json_encode($data),
  ],
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);

echo $result;
?>

package main

import (
	"bytes"
	"net/http"
)

func main() {
	jsonData := []byte(`{
		"faceImageBase64":"<base64-face>"
	}`)

	req, _ := http.NewRequest("POST",
		"https://dev-idf-gw.cognetlabs.org/api/gw/services/liveness",
		bytes.NewBuffer(jsonData),
	)

	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("x-api-key", "YOUR_API_KEY")

	client := &http.Client{}
	client.Do(req)
}

import okhttp3.*;

public class Main {
    public static void main(String[] args) throws Exception {

        OkHttpClient client = new OkHttpClient();

        String json = "{\"faceImageBase64\":\"<base64-face>\", \"faceImageFileName\":\"selfie.jpg\" }";

        RequestBody body = RequestBody.create(
            json, MediaType.parse("application/json")
        );

        Request request = new Request.Builder()
            .url("https://dev-idf-gw.cognetlabs.org/api/gw/services/liveness")
            .addHeader("x-api-key", "YOUR_API_KEY")
            .post(body)
            .build();

        Response response = client.newCall(request).execute();
        System.out.println(response.body().string());
    }
}

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://dev-idf-gw.cognetlabs.org/api/gw/services/liveness")

header = {
  'Content-Type': 'application/json',
  'x-api-key': 'YOUR_API_KEY'
}

payload = {
  faceImageBase64: "<base64-face>",
  faceImageFileName: "selfie.jpg"
}

http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = payload.to_json

response = http.request(request)
puts response.body

200

{
"success":true,
"requestId":"5d5046368688",
"correlationId":"corr-1777474602158",
"data":{
"isLive":false,
"confidenceScore":null,
"livenessStatus":"Declined"
},
"error":null,
"durationMs":3708,
"processedAt":"2026-04-29T14:56:46.0468574Z"
}

{
  "error": "FaceImageBase64 is required"
}