Reconhecimento Facial 1:N: Encontrar Todas as Contas Controladas por uma Pessoa (PT-PT)

Um operador a gerir quarenta contas na sua plataforma tem quarenta endereços de e-mail, provavelmente quarenta instrumentos de pagamento e possivelmente quarenta dispositivos. O que não têm são quarenta rostos.

Se alguma parte do seu fluxo de acesso capturar uma selfie, já está a guardar o único identificador que é genuinamente caro de multiplicar. A Pesquisa Facial 1:N é a chamada que o utiliza — um pedido, um rosto, e de volta vem cada conta no seu próprio sistema que a mesma pessoa verificou.

É gratuito com a verificação de identidade Didit, devolve em menos de dois segundos e é executado automaticamente durante a prova de vida dentro de uma sessão de verificação.

Principais pontos

• POST /v3/face-search/ pesquisa um rosto em relação aos rostos que a sua própria aplicação registou — sessões executadas com save_api_request=true — não um índice global partilhado.
• As correspondências retornam com os seus próprios vendor_data em cada uma, para que os resultados sejam mapeados diretamente para os seus IDs de conta.
• Dois modos: most_similar para deduplicação e utilizadores recorrentes, blocklisted_or_approved para rastreio de lista negra.
• status é "Declined" apenas numa correspondência de lista negra. Duplicados retornam "Approved" com um aviso DUPLICATED_FACE — informativo por design, porque a política de deduplicação é sua.
• A resposta é um objeto face_search singular, não um array. Isto confunde as pessoas.
• Gratuito com a verificação Didit. Resposta em menos de dois segundos. Executa automaticamente durante a prova de vida.

O que significa 1:N e porque é a ferramenta certa

Uma correspondência facial 1:1 responde "esta é a pessoa neste documento?". Essa é uma questão de verificação, e é o que é executado durante o onboarding.

Uma pesquisa 1:N responde a uma pergunta diferente: "de todas as pessoas que já verifiquei, esta é uma delas?". Uma imagem entra, e cada correspondência no seu índice sai.

Para o abuso coordenado de contas, a segunda questão é a que importa. O relatório da Anthropic sobre campanhas de destilação descreveu a atribuição construída a partir de sinais relacionais — métodos de pagamento partilhados, tempo coordenado, infraestrutura partilhada. Uma pesquisa biométrica 1:N é a mesma classe de sinal, obtida do identificador mais caro que um operador tem para multiplicar.

O índice é seu. A Pesquisa Facial é executada em relação aos rostos que a sua própria aplicação registou através de verificações anteriores — sessões com save_api_request=true, ou Prova de Vida Passiva com save_api_request=true. Não é uma pesquisa entre utilizadores de outros clientes Didit. Se não registou rostos, não há nada para pesquisar.

A API

Pedido

curl -X POST 'https://verification.didit.me/v3/face-search/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -F 'user_image=@./selfie.jpg' \
  -F 'search_type=most_similar' \
  -F 'save_api_request=true' \
  -F 'vendor_data=acct_8842'

multipart/form-data, autenticado com x-api-key.

Obrigatório: user_image — jpg, jpeg, png, tiff ou webp, máximo 5 MB. PDFs não são aceites. A imagem deve conter pelo menos um rosto detetável; quando vários estão presentes, o maior limite vence.

Opcional:

• search_type — most_similar (padrão) para deduplicação e deteção de utilizadores recorrentes, ou blocklisted_or_approved para rastreio de lista negra.
• save_api_request — registar esta imagem no seu índice.
• vendor_data — o seu próprio identificador para o assunto.

Resposta

A resposta contém um objeto face_search singular. A maioria das funcionalidades Didit retorna arrays plurais, por isso esta é a única forma que vale a pena ler cuidadosamente antes de escrever o parser.

{
  "request_id": "...",
  "face_search": {
    "status": "Approved",
    "total_matches": 12,
    "matches": [
      {
        "session_id": "...",
        "session_number": 4471,
        "similarity_percentage": 97.4,
        "vendor_data": "acct_3310",
        "verification_date": "2026-06-02T09:14:00Z",
        "user_details": { },
        "match_image_url": "...",
        "status": "Approved",
        "is_blocklisted": false
      }
    ],
    "user_image": { "entities": [] },
    "warnings": []
  }
}

Os campos que transportam a investigação:

• total_matches — quantas contas partilham este rosto.
• vendor_data em cada correspondência — o seu identificador, para que uma lista de correspondências seja imediatamente uma lista de contas.
• similarity_percentage — a força de cada correspondência individual.
• verification_date — a linha do tempo. Doze contas verificadas ao longo de onze meses são lidas de forma diferente de doze verificadas numa tarde.
• is_blocklisted — se esta correspondência já está na sua lista negra.
• session_id — o pivô para tudo o mais que a sessão capturou, incluindo os avisos do dispositivo e da rede.

Semântica do estado

Este é o comportamento mais importante em todo o endpoint:

status é "Declined" apenas quando pelo menos uma correspondência de lista negra é encontrada. Correspondências duplicadas puras retornam "Approved".

Uma duplicata não é uma recusa. É informação. A Didit recusa-se deliberadamente a tomar a decisão de deduplicação por si, porque as duplicatas têm explicações legítimas e só você conhece as regras do seu produto.

Avisos

Aviso	Significado
FACE_IN_BLOCKLIST	Correspondência definitiva na lista negra — rejeitar
POSSIBLE_FACE_IN_BLOCKLIST	Correspondência limítrofe abaixo do limite rígido — encaminhar para revisão manual
DUPLICATED_FACE	Este rosto já está verificado sob diferentes vendor_data
POSSIBLE_DUPLICATED_FACE	Duplicata limítrofe
MULTIPLE_FACES_DETECTED	Mais de um rosto na imagem submetida

Modos de falha

• HTTP 400 — nenhum rosto detetado em user_image. Pedir uma nova captura.
• HTTP 403 — sem créditos.
• status: "Declined" com FACE_IN_BLOCKLIST — acerto definitivo. Rejeitar.
• POSSIBLE_FACE_IN_BLOCKLIST — abaixo do limite rígido. Revisão manual.
• DUPLICATED_FACE — já verificado sob diferentes vendor_data. Fundir, bloquear ou permitir de acordo com a sua política.

O caminho automático

Muitas vezes não precisa de chamar o endpoint de todo. A Pesquisa Facial é executada automaticamente durante a prova de vida dentro de uma sessão de verificação:

• Os dados biométricos faciais são comparados com todos os utilizadores previamente verificados.
• Contas duplicadas potenciais são identificadas por similaridade facial.
• As correspondências são sinalizadas de acordo com os seus limites de similaridade configurados.
• Os rostos são verificados em relação à sua lista negra, e uma correspondência na lista negra recusa automaticamente a verificação.

Assim, para qualquer nível onde já executa a verificação completa, a deteção de duplicados está incluída sem custo adicional e sem chamada extra. O endpoint autónomo é para os casos que o fluxo da sessão não cobre — investigar uma conta após o facto, rastrear uma imagem que obteve de outra forma, ou mudar o search_type para executar uma pesquisa focada na lista negra sobre uma imagem que já possui.

Transformar correspondências num mapa de atores

O fluxo de trabalho prático, começando por uma conta suspeita:

1. Pesquisar o rosto. total_matches: 12 — doze contas, uma pessoa.
2. Ler o vendor_data. Doze dos seus próprios IDs de conta, sem necessidade de junção.
3. Ler a linha do tempo. Agrupar os valores de verification_date. Contas criadas em surtos são operacionalmente diferentes de contas criadas ao longo de anos.
4. Pivotar em session_id. Puxar os avisos de dispositivo e rede de cada sessão. Rostos que partilham DUPLICATED_DEVICE_FINGERPRINT apertam o cluster; contas em dispositivos não relacionados podem ser um arranjo diferente.
5. Expandir. Dispositivos e intervalos de IP descobertos no passo 4 puxarão contas que a pesquisa facial perdeu — porque uma pessoa diferente completou essas verificações.
6. Decidir uma vez, aplicar em todos os identificadores. Se o cluster for abuso confirmado, publique o reference_session_id confirmado em cada tipo de lista negra que lhe interessa — rosto, dispositivo, IP, e-mail, telefone, documento. É uma chamada por lista, e cada chamada extrai automaticamente o valor certo dessa sessão, para que nada seja digitado à mão.

Seis passos, um ponto de partida, e nenhuma inspeção de prompt em qualquer lugar. A camada de tráfego diz-lhe algo está errado com esta conta. Isto diz-lhe quantas contas isso realmente é.

Vale a pena afirmar claramente: uma pesquisa facial 1:N não impede a extração de modelos e não a deteta. A Pesquisa Facial não tem visibilidade no tráfego da sua API. Resolve contas a pessoas, o que lhe permite agir sobre um alerta num cluster inteiro em vez de uma única linha. Os controlos de saída ao nível do modelo e a deteção de tráfego semântico são camadas separadas, e continuam a ser responsabilidade do fornecedor do modelo.

Casos de uso

Plataformas de API de IA a resolver um alerta comportamental no conjunto completo de contas que um operador controla.

Abuso de níveis gratuitos e créditos — uma pessoa, muitas contas de teste, é o mesmo problema de deteção com riscos mais baixos.

Marketplaces e plataformas de trabalho temporário a detetar vendedores, motoristas ou estafetas banidos a registarem-se novamente.

iGaming a aplicar regras de conta única e autoexclusão, onde um jogador excluído que retorna é uma falha regulatória, não apenas um caso de abuso.

Serviços financeiros a identificar anéis de identidade sintética onde um rosto real é distribuído por muitas identidades fabricadas.

Perguntas frequentes

O meu índice facial é partilhado com outros clientes Didit?

Não. A Pesquisa Facial é executada em relação ao índice que a sua própria aplicação construiu através das suas próprias verificações. Não é uma pesquisa entre clientes.

O que controla a entrada de um rosto no índice?

save_api_request=true numa sessão de verificação ou numa chamada de Prova de Vida Passiva. Você decide o que é registado e controla a retenção, consistente com o seu próprio aviso de privacidade e base legal para o processamento de dados biométricos.

Que limite de similaridade devo usar?

Esteja ciente de onde a afinação se aplica. No endpoint autónomo, as bandas de similaridade que separam acertos confirmados (FACE_IN_BLOCKLIST, DUPLICATED_FACE) de possíveis acertos (POSSIBLE_FACE_IN_BLOCKLIST, POSSIBLE_DUPLICATED_FACE) são fixas internamente — a afinação do limite por aplicação aplica-se à verificação de prova de vida do fluxo de trabalho, não a POST /v3/face-search/. Assim, no caminho autónomo, leia similarity_percentage por correspondência e aplique a sua própria barra na lógica da aplicação, e trate os avisos POSSIBLE_* como a sua fila de revisão em vez da sua fila de recusa.

Quão rápido é em escala?

Resposta em menos de dois segundos.

Posso pesquisar um rosto que nunca passou pela verificação Didit?

Sim. Qualquer user_image num formato aceite funciona. Se nenhum rosto for detetado, a chamada retorna HTTP 400.

É mesmo gratuito?

Sim — a Pesquisa Facial 1:N é gratuita com a verificação de identidade Didit. Não há custo por pesquisa. Está a pagar pelas verificações que constroem o índice, a 0,33 $ pelo pacote completo, com as primeiras 500 gratuitas por mês.

E se a mesma pessoa tiver legitimamente duas contas?

Então DUPLICATED_FACE é exatamente o sinal informativo que se destina a ser — é por isso que não recusa. Funda-as, permita-as ou pergunte ao utilizador, de acordo com as regras do seu produto.

Pronto para começar?

A Pesquisa Facial está disponível em todas as contas Didit, sem necessidade de comprar um produto separado.

• Leia a documentação — Visão geral da Pesquisa Facial 1:N e a API de Listas para listas negras faciais.
• Veja o produto — Verificação de Utilizador.
• Verifique os preços — A Pesquisa Facial 1:N é gratuita; o pacote de verificação que constrói o índice custa 0,33 $.
• Comece gratuitamente — business.didit.me, 500 verificações KYC por mês sem custo.