API de Reconocimiento Facial

¿Qué es el FR-API?

El FR-API convierte cada rostro en un vector de 512 dimensiones y los compara por similitud de coseno sobre una base vectorial. Detecta si dos fotos corresponden a la misma persona, aunque provengan de plataformas distintas. Su objetivo es ayudar a cruzar y unificar reportes de personas desaparecidas tras el terremoto de Venezuela 2026.

Es asistivo: cada resultado trae un score de similitud y siempre debe confirmarse por una persona antes de tomar decisiones (fusionar, eliminar, contactar).

Cruzar tu base de datos y detectar duplicados

Dos pasos: (1) subes tus registros al índice una vez, y (2) pides los duplicados. Re-ejecuta el paso 1 al agregar registros nuevos (es idempotente, solo añade lo nuevo).

Paso 1 — Indexar tu base

Un POST /v1/index por persona. Solo entran fotos con rostro (las demás devuelven indexed:false, sin fallar).

# Sube/indexa UN registro de tu base. Idempotente por external_id (tu id).
curl -X POST "https://fr-api.reportavnzla.com:8443/v1/index" \
  -H "X-API-Key: TU_API_KEY" \
  -F "external_id=ID_EN_TU_BD" \
  -F "person_name=Katherine Mendoza" \
  -F "last_seen_location=Catia la Mar" \
  -F "image_url=https://tu-cdn/fotos/123.jpg"   # o  -F "file=@foto.jpg"
# -> {"ok":true,"indexed":true,"record_id":"tu-fuente:ID_EN_TU_BD"}

Recorriendo tu BD (Node.js):

const FR  = "https://fr-api.reportavnzla.com:8443";
const KEY = "TU_API_KEY";
const sleep = (ms) => new Promise(r => setTimeout(r, ms));

// 1) trae TUS registros (ajusta a tu BD)
const personas = await db.query(
  "SELECT id, nombre, ubicacion, foto_url FROM personas"
);

// 2) súbelos al índice (idempotente; reanudable)
for (const p of personas) {
  if (!p.foto_url) continue;                  // sin foto no se compara
  const fd = new FormData();
  fd.append("external_id", String(p.id));     // tu id → no duplica
  fd.append("person_name", p.nombre ?? "");
  fd.append("last_seen_location", p.ubicacion ?? "");
  fd.append("image_url", p.foto_url);
  const r = await fetch(FR + "/v1/index",
    { method: "POST", headers: { "X-API-Key": KEY }, body: fd });
  console.log(p.id, (await r.json()).indexed ? "ok" : "sin-rostro");
  await sleep(550);                            // ~110/min < límite 120/min
}

Paso 2 — Pedir los duplicados

Opción rápida: /v1/duplicates te devuelve los pares (con los dos ids de tu BD, el score y las dos fotos para revisar). Pasa el mismo source con que indexaste en el paso 1.

# Cruza TU base por rostro y lista pares duplicados.
# "source" debe ser EL MISMO con que indexaste (paso 1). Por defecto es la
# etiqueta de tu API key; si indexaste con otro source, pásalo igual aquí.
curl "https://fr-api.reportavnzla.com:8443/v1/duplicates?source=TU_FUENTE&min_score=0.6&limit=500" \
  -H "X-API-Key: TU_API_KEY"

{
  "checked": 500,
  "duplicates": [
    { "a": "tu-fuente:12", "b": "tu-fuente:88", "score": 0.94,
      "a_name": "José Pérez",  "b_name": "Jose Perez",
      "a_image": "https://…",  "b_image": "https://…" }
  ]
}

⚠️ /v1/duplicates revisa hasta 500 registros por llamada. Si tu base es mayor y quieres cobertura total con un solo endpoint, escríbenos para subir el límite/añadir paginación — o usa la opción de abajo.

Opción de cobertura total (bases > 500): una búsqueda por registro; de paso detecta si la persona está también en otras plataformas.

// Cobertura TOTAL (bases > 500): una búsqueda por registro.
const UMBRAL = 0.6, vistos = new Set(), duplicados = [];

for (const p of personas) {
  if (!p.foto_url) continue;
  const fd = new FormData();
  fd.append("file", await (await fetch(p.foto_url)).blob());
  const { results = [] } = await (await fetch(FR + "/v1/search",
    { method: "POST", headers: { "X-API-Key": KEY }, body: fd })).json();

  for (const m of results) {
    const yoMismo = m.record_id === "tu-fuente:" + p.id;
    if (yoMismo || m.score < UMBRAL) continue;
    if (m.source === "tu-fuente") {            // duplicado DENTRO de tu base
      const k = [String(p.id), m.record_id].sort().join("|");
      if (!vistos.has(k)) { vistos.add(k); duplicados.push({ a: p.id, b: m.record_id, score: m.score }); }
    }
    // m.source !== "tu-fuente"  → la misma persona en OTRA plataforma
  }
  await sleep(550);
}
console.table(duplicados);   // pares para revisión humana

Paso 3 — Revisar (humano) y limpiar

Empieza por los pares de banda alta. Muestra las dos fotos a un revisor; si confirma, fusionas/eliminas en tu BD. El FR no borra nada por ti.

Multi-rostro y recuadros (verde / amarillo)

Si la imagen tiene varias personas, se coteja cada rostro. La respuesta de /v1/check-duplicate y /v1/search incluye un arreglo faces con un elemento por rostro detectado, listo para dibujar recuadros: verde si coincide (≥ 0.51), amarillo si no.

{
  "ok": true, "faces_detected": 2, "min_score": 0.51,
  "possible_duplicate": true,
  "faces": [
    { "bbox": [67,117,132,215], "matched": true,  "color": "green",
      "best_score": 0.99, "band": "alta", "candidates": [ /* … */ ] },
    { "bbox": [240,110,300,205], "matched": false, "color": "yellow",
      "best_score": 0.0, "band": null, "candidates": [] }
  ],
  "candidates": [ /* coincidencias agregadas de todos los rostros, score >= 0.51 */ ]
}

bbox = [x1,y1,x2,y2] en píxeles de la imagen enviada. matched/color indican el recuadro; best_score el mejor parecido de ese rostro; candidates sus coincidencias.