> API de busca facial por IA: envie uma foto e receba os perfis públicos onde o rosto aparece, com score de confiança. Um crédito por busca, sem assinatura. **API DE BUSCA FACIAL POR IA** # BUSCA FACIAL POR IA, DIRETO DO SEU CÓDIGO. Uma **API de busca facial reversa** sobre a web pública. Envie uma foto de um rosto e receba as páginas e perfis onde aquele rosto aparece, cada um com um score de confiança e um link. Um crédito por busca, com preço em dólares, sem assinatura e sem mínimo mensal. Sem ligação de vendas · Sem mínimo mensal · Créditos nunca expiram Também no [RapidAPI](https://rapidapi.com/muratcankuruoffical/api/trace-reverse-face-search-api) · [especificação OpenAPI](https://traceaifacescan.app/openapi.json) · [exemplos de código no GitHub](https://github.com/muratcankuruoffical/reverse-face-search-api) · [Hugging Face Space](https://huggingface.co/spaces/muratcankuru/reverse-face-search) · [Apify Actor](https://apify.com/muratcankuru/reverse-face-search) - Resultados em cerca de um minuto - Um crédito por busca - REST + JSON, nada para instalar - Motor próprio, não um revendedor **O QUE A API FAZ** ## UMA FOTO ENTRA. TODA CORRESPONDÊNCIA PÚBLICA SAI. O mesmo motor que o painel usa, com os mesmos resultados. A API não é uma versão reduzida. **BUSCA FACIAL REVERSA** ### Compara um rosto, não um arquivo. Uma busca reversa de imagem comum encontra cópias da mesma imagem. Isso compara o rosto, então uma foto diferente da mesma pessoa — outra roupa, outro ano — ainda volta como resultado. **SCORE DE CONFIANÇA** ### Cada correspondência traz um número. Cada resultado tem um score de similaridade de 50 a 100 e uma faixa: possível a partir de 70, forte a partir de 80, quase certo a partir de 90. Nada é retornado como veredito. **PERFIS SOCIAIS** ### A conta, não só a página. Quando a URL pertence a uma conta, o nome de usuário e a plataforma voltam como campos separados — sem precisar analisar URLs do seu lado. **NOSSO PRÓPRIO MOTOR** ### Não somos revendedores. A Trace opera seu próprio serviço de busca facial. É por isso que uma busca custa centavos em vez de dólares, e por isso não precisamos limitar suas requisições. **INÍCIO RÁPIDO** ## TRÊS CHAMADAS, DO INÍCIO AO FIM. A autenticação é um único cabeçalho. Não há SDK para instalar nem handshake. ### Iniciar uma varredura Multipart, campo `image`. JPEG, PNG ou WebP, até 8 MB, com pelo menos 200px no lado mais curto. `Idempotency-Key` é opcional e torna uma nova tentativa segura. ```bash curl -X POST https://traceaifacescan.app/api/v1/scans \ -H "Authorization: Bearer trk_live_..." \ -H "Idempotency-Key: $(uuidgen)" \ -F image=@face.jpg ``` **202 ACCEPTED** ```json { "id": "01m0jr1j5cbhwqsnt5qjx3zyd8", "status": "queued", "progress": 0, "locked": false, "match_count": 0, "credits_remaining": 9 } ``` ### Consulte periodicamente até terminar Uma busca leva de 25 a 45 segundos. Consulte a cada um ou dois segundos até que `status` seja `done` ou `failed`. ```bash curl https://traceaifacescan.app/api/v1/scans/01m0jr1j5cbhwqsnt5qjx3zyd8 \ -H "Authorization: Bearer trk_live_..." ``` **200 OK** ```json { "status": "done", "progress": 100, "locked": false, "match_count": 2, "matches": [ { "score": 88, "tier": "strong", "platform": "x", "handle": "@alexrivers88", "url": "https://x.com/alexrivers88", "preview_url": ".../scans/01m0.../previews/0" } ] } ``` ### Gastar o crédito Uma varredura criada sem créditos disponíveis volta `locked: true` sem correspondências — nada foi pesquisado. Revelar é uma chamada separada de propósito: um script que percorre uma lista de varreduras não deve conseguir esvaziar seu saldo por acidente. ```bash curl -X POST \ https://traceaifacescan.app/api/v1/scans/01m0.../reveal \ -H "Authorization: Bearer trk_live_..." ``` **ENDPOINTS** ## TODA A SUPERFÍCIE. Sete endpoints. A definição legível por máquina está em [openapi.json](https://traceaifacescan.app/openapi.json), e a referência completa com os corpos de resposta está em [a documentação](https://traceaifacescan.app/docs). - **POST** — `/v1/scans` — Inicia uma varredura a partir de uma foto. - **GET** — `/v1/scans/{id}` — Status, progresso e correspondências. - **GET** — `/v1/scans` — Suas varreduras, paginadas. - **POST** — `/v1/scans/{id}/reveal` — Gasta um crédito e executa a busca real. - **GET** — `/v1/scans/{id}/previews/{n}` — A miniatura do rosto de uma correspondência. - **DELETE** — `/v1/scans/{id}` — Exclui a varredura, sua imagem e suas pré-visualizações. - **GET** — `/v1/account` — Seu saldo de créditos. **ERROS E LIMITES** ## FALHAS PREVISÍVEIS. Erros voltam como `application/problem+json` com uma string `code` estável. Compare pelo código, nunca pela mensagem. - **402** — `insufficient_credits` — Sem créditos restantes. Nada foi pesquisado e nada foi cobrado. - **404** — `no_face_detected` — Nenhum rosto na imagem. Use outra foto, não tente de novo com a mesma. - **429** — `rate_limited` — Só após falhas repetidas de autenticação. `Retry-After` indica quando. - **401** — `unauthorized` — Chave ausente, incorreta ou revogada. - **503** — `provider_unavailable` — Erro nosso. Um crédito reservado para uma busca que falhou é sempre devolvido. ### Limites - **Sem limite de taxa de requisições.** Leituras não são contadas e não há teto por minuto. - Seu limite real é o seu **saldo de créditos**: uma varredura custa um crédito, uma leitura não custa nada. - Imagens de até **8 MB**, com pelo menos **200px** no lado mais curto. - Varreduras e suas imagens são excluídas após **30 dias**. `DELETE` faz isso imediatamente. **PREÇOS** ## UM CRÉDITO, UMA BUSCA. Os mesmos créditos que o painel usa, do mesmo saldo. Sem assinatura, sem mínimo mensal, e eles nunca expiram. O pacote de 100 créditos é aquele em torno do qual a API foi construída. Compre com cartão, com Telegram Stars ou com criptomoeda — veja [os pacotes de créditos](https://traceaifacescan.app/pt/#pricing). Precisa de um volume maior que o maior pacote? [Fale com a gente](https://docs.google.com/forms/d/e/1FAIpQLSdVeyYm3BLWkEnmHToK5_JQynOHCctKTxMkBJp3PJf-pmaLYQ/viewform). **LIMITES HONESTOS** ## O QUE ESTA API NÃO FAZ. **Não é um serviço de identidade.** Uma correspondência é um score de similaridade entre duas imagens, não uma afirmação sobre quem alguém é. Não há nome, endereço, telefone nem registro de qualquer tipo na resposta — apenas URLs públicas e um número. **Um resultado vazio não é prova de ausência.** Significa apenas que nada foi encontrado na parte da web pública que conseguimos alcançar. Se a pessoa não tem nenhuma foto pública, não há nada para encontrar, e nenhuma API pode mudar isso. **Nada protegido por login é acessado.** Todo resultado é uma página que já era pública. **Não deve ser usada para verificação de antecedentes, contratação, crédito, seguros, vigilância ou aplicação da lei**, nem contra menores. Envie apenas fotos que você tem o direito de pesquisar. Isso está nos [Termos de Uso](https://traceaifacescan.app/pt/termos/) e nós fiscalizamos isso — uma chave usada dessa forma é revogada. **FAQ** ## O QUE OS DESENVOLVEDORES PERGUNTAM PRIMEIRO. ### O que é uma API de busca facial por IA? É uma API HTTP que recebe uma fotografia de um rosto e retorna os outros lugares na internet pública onde aquele mesmo rosto aparece. Diferente de uma busca reversa de imagem, que compara arquivos de imagem, uma busca facial por IA compara a geometria do rosto — então ela reconhece a mesma pessoa em uma foto completamente diferente. A versão da Trace é uma API REST com respostas em JSON: um POST para iniciar uma varredura, um GET para ler as correspondências. ### Quanto custa uma busca facial pela API? Um crédito por busca, e os créditos são comprados em pacotes com preço em dólares americanos — de $4 por cinco créditos a $50 por 100. Não há assinatura, mínimo mensal nem expiração. A API gasta do mesmo saldo que o painel. ### Vocês têm um plano gratuito ou um teste? Não há busca gratuita na API. Uma requisição da API feita por uma conta sem créditos cria a varredura, mas não a executa: ela volta bloqueada, sem correspondências. O painel mostra a um visitante conectado um resultado de amostra estático para que veja o formato de um caso finalizado, e a API deliberadamente nunca retorna isso — um placeholder é algo sobre o qual um script construiria lógica. ### Quão rápida é uma busca? Cerca de 25 a 45 segundos de ponta a ponta, às vezes até 90. A API é assíncrona por esse motivo: o POST retorna 202 imediatamente com um id, e você faz polling nele. Manter uma requisição HTTP aberta por um minuto transformaria uma conexão fechada em uma busca cancelada. ### Posso usar URLs de imagem em vez de enviar um arquivo? Não na v1. Aceitar uma URL transformaria a API em um proxy SSRF — estaríamos buscando endereços arbitrários em nome de quem chama, de dentro da nossa rede. Se isso vier a existir, será com uma lista de permissões e faixas de IP privadas bloqueadas. ### A API tem limite de taxa? Não. Chame na velocidade que o seu código permitir — leituras não são contadas e não há teto por minuto. A única coisa que te limita é o seu saldo de créditos, porque uma varredura custa um crédito e uma leitura não custa nada. Resta um único freio de segurança, e uma chave válida nunca o vê: tentativas repetidas de autenticação falhada do mesmo endereço são desaceleradas, para que adivinhar chaves continue caro. ### É legal usar uma API de busca facial? Depende totalmente do uso que você faz e de onde você está. Verificar se uma foto na sua própria plataforma pertence à pessoa que a está usando é bem diferente de montar um banco de dados de rostos. Dados faciais são uma categoria especial sob o GDPR e a KVKK, e você é o controlador de tudo que nos envia. Leia os Termos de Uso: verificação de antecedentes, contratação, crédito, seguros, vigilância e aplicação da lei estão todos fora dos limites. ### Isso é uma API de reconhecimento facial ou uma API de busca reversa de imagem? É uma API de busca facial, que é um tipo específico de reconhecimento facial. Ela não compara duas fotos que você envia, não verifica um documento de identidade nem retorna nada sobre quem uma pessoa é. Ela recebe uma fotografia e pesquisa na web pública outras imagens do mesmo rosto, retornando cada correspondência como uma URL pública com um score de similaridade. É isso também que a diferencia de uma API de busca reversa de imagem: a busca reversa de imagem compara o arquivo de imagem, então encontra cópias daquela imagem exata, enquanto esta compara a geometria facial e encontra o mesmo rosto em uma foto diferente. **API DE BUSCA FACIAL POR IA** ## COMECE COM UMA CHAMADA. Crie uma chave no painel e o primeiro curl já funciona.