Comparación Facial

Endpoint

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

Compara una imagen de prueba contra una o más imágenes de galería y retorna un puntaje de similitud. Usa search_mode para balancear velocidad y precisión.

Headers

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

Parámetros

Name	Type	Required	Description
probe	string[]	Sí	Array con al menos una cadena de imagen base64.
gallery	string[]	Sí	Array de cadenas de imagen base64 para comparar.
search_mode	string	Sí	Uno de FAST o ACCURATE.
compare_min_score	number	No	Umbral de aprobación del score de comparación (0.67–0.95). Por defecto: 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", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.VERIFIK_TOKEN}`,
    },
    body: JSON.stringify({
      probe: ["<base64>"];
      gallery: ["<base64>", "<base64>"];
      search_mode: "ACCURATE"
    }),
  });
  console.log(await res.json());
}

run();

PHP

<?php
$ch = curl_init("https://api.verifik.co/v2/face-recognition/compare");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer " . getenv("VERIFIK_TOKEN")
]);
$body = json_encode([
    "probe" => ["<base64>"],
    "gallery" => ["<base64>", "<base64>"],
    "search_mode" => "FAST"
]);
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"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.getenv('VERIFIK_TOKEN')}"
}
payload = {
    "probe": ["<base64>"],
    "gallery": ["<base64>", "<base64>"],
    "search_mode": "FAST"
}
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": []string{"<base64>"},
        "gallery": []string{"<base64>", "<base64>"},
        "search_mode": "ACCURATE",
    }
    b, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.verifik.co/v2/face-recognition/compare", 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": "AB12C",
  "data": {
    "score": 0.91
  },
  "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 (compareMinScore)
API directa (compare_min_score)	0.67–0.95 (por defecto 0.85 si se omite)

Las caras de documentos impresos (por ejemplo foto de CC colombiana vs selfie en vivo) suelen puntuar más bajo que coincidencias en vivo vs en vivo. Un score alrededor de 0.67–0.75 puede ser una coincidencia válida para galerías de documentos impresos; bajar el umbral aumenta la aceptación de coincidencias genuinas y puede subir falsos positivos. Prefiere imágenes enfocadas en el rostro; cropFace en servidor no está soportado en los endpoints de face-recognition compare (omite el campo; prepara recortes en el cliente si hace falta).

Notas

• probe y gallery deben ser cadenas base64; las imágenes más cortas que ~100 caracteres son rechazadas con 412:only_images_in_base64.
• search_mode debe ser FAST o ACCURATE (requerido por validación).
• La respuesta está envuelta con id, data, y signature según el middleware estándar.
• No existe GET /v2/face-verifications/:id. Para leer el resultado de comparación en SmartEnroll, usa GET /v2/app-registrations/:id?populates[]=compareFaceVerification. Los registros FaceVerification expiran en unos 90 días en producción (menos en desarrollo).