Comparar con Detección de Vitalidad (Secuencial)

Endpoint

POST https://api.verifik.co/v2/face-recognition/compare-with-liveness

Realiza la comparación primero y, si la comparación cumple con compare_min_score (o si no se proporciona), procede a la detección de vitalidad en la prueba con liveness_min_score.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Parámetros

Name	Type	Required	Description
probe	string	Sí	Cadena de imagen base64 para la captura en vivo.
gallery	string[]	Sí	Array de cadenas de imagen base64 para comparar. Se admiten URLs y serán descargadas y convertidas internamente.
search_mode	string	Sí	Uno de FAST o ACCURATE.
liveness_min_score	number	No	Umbral de vitalidad; por defecto 0.6 si no se proporciona.
compare_min_score	number	No	Umbral de comparación opcional (0.67–0.95). El valor por defecto en SmartEnroll hospedado es 0.85.

Solicitud

Node.js

const fetch = require("node-fetch");

async function run() {
  const res = await fetch("https://api.verifik.co/v2/face-recognition/compare-with-liveness", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.VERIFIK_TOKEN}`,
    },
    body: JSON.stringify({
      probe: "<base64>",
      gallery: ["<base64>"],
      search_mode: "FAST",
      liveness_min_score: 0.6,
      compare_min_score: 0.8
    }),
  });
  console.log(await res.json());
}

run();

PHP

<?php
$ch = curl_init("https://api.verifik.co/v2/face-recognition/compare-with-liveness");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer " . getenv("VERIFIK_TOKEN")
]);
$body = json_encode([
    "probe" => "<base64>",
    "gallery" => ["<base64>"],
    "search_mode" => "ACCURATE",
    "liveness_min_score" => 0.6,
    "compare_min_score" => 0.8
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Python

import os, requests

url = "https://api.verifik.co/v2/face-recognition/compare-with-liveness"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.getenv('VERIFIK_TOKEN')}"
}
payload = {
    "probe": "<base64>",
    "gallery": ["<base64>"],
    "search_mode": "FAST",
    "liveness_min_score": 0.6,
    "compare_min_score": 0.8
}
r = requests.post(url, json=payload, headers=headers)
print(r.json())

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    payload := map[string]interface{}{
        "probe": "<base64>",
        "gallery": []string{"<base64>"},
        "search_mode": "FAST",
        "liveness_min_score": 0.6,
        "compare_min_score": 0.8,
    }
    b, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.verifik.co/v2/face-recognition/compare-with-liveness", bytes.NewBuffer(b))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer "+os.Getenv("VERIFIK_TOKEN"))
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    var out map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&out)
    fmt.Println(out)
}

Respuesta

200

{
  "id": "CWL01",
  "data": {
    "comparison": {
      "score": 0.88
    },
    "liveness": {
      "liveness_score": 0.91,
      "min_score": 0.6,
      "passed": true
    }
  },
  "signature": {
    "message": "Certified by Verifik.co",
    "dateTime": "January 16, 2024 3:44 PM"
  }
}

401/403

{
  "message": "Authentication required",
  "code": "UNAUTHORIZED"
}

o

{
  "message": "token_expired",
  "code": "FORBIDDEN"
}

409

{
  "message": "\"search_mode\" is required",
  "code": "MissingParameter"
}

412

{
  "message": "only_images_in_base64",
  "code": "ERROR"
}

500

{
  "message": "internal_error",
  "code": "ERROR"
}

Umbrales de comparación facial

Contexto	Valores típicos / permitidos
SmartEnroll hospedado / project flow (por defecto)	0.85
API directa (compare_min_score)	0.67–0.95

Las caras de documentos impresos vs selfies en vivo suelen puntuar más bajo que en vivo vs en vivo. Valores cerca del mínimo de la API (0.67) pueden ser apropiados para galerías de CC impresa tras validar el riesgo de falsos aceptados. cropFace en servidor no está soportado en este endpoint (se ignora si se envía); envía imágenes enfocadas en el rostro.

Notas

• La comparación se ejecuta primero. Solo si compare_min_score no se proporciona o se cumple, se ejecuta la detección de vitalidad en probe.
• liveness_min_score por defecto es 0.6 si no se proporciona.
• La galería admite URLs https y serán descargadas y convertidas a base64 internamente.
• No existe GET /v2/face-verifications/:id. Para historial SmartEnroll, popula compareFaceVerification en el app registration (TTL ~90 días en producción).