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)
SmartEnroll hospedado / project flow (rango permitido)	0.65–0.95
API directa (compare_min_score)	0.67–0.95 (por defecto 0.85 si se omite)

Los retratos impresos en documentos suelen estar desgastados, rayados o a baja resolución. Algunas cédulas colombianas son especialmente pobres, y el mismo problema de calidad puede aparecer en otros países. Un selfie en vivo vs una foto impresa puntúa más bajo que en vivo vs en vivo. Un score alrededor de 0.65–0.75 puede ser una coincidencia válida para galerías de documentos impresos. Bajar el umbral hospedado hacia 0.65 aumenta la aceptación de coincidencias genuinas y puede subir falsos aceptados. Conserva 0.85 salvo que veas fallos reales. 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).