Documentação da API

Autenticação

Todas as chamadas exigem o cabeçalho X-API-Key com a chave fornecida por nós. A chave identifica o seu acesso e delimita quais eventos você enxerga — não compartilhe publicamente nem a exponha em código de front-end.

X-API-Key: sua-chave-de-acesso

O host base é https://busca.framematcher.com. O identificador {evento} usado nas rotas é fornecido junto com a chave.

1 · Busca por selfie

Envie uma selfie e receba a lista de todas as fotos do evento em que aquela pessoa aparece, ordenadas por destaque — fotos individuais, nítidas, frontais e bem enquadradas primeiro.

Requisição

A imagem vai como corpo binário, com o Content-Type correspondente (image/jpeg, image/png ou image/webp) — até 10 MB, contendo um único rosto.

curl -X POST https://busca.framematcher.com/v1/partner/events/{evento}/search \
     -H "X-API-Key: SUA_CHAVE" \
     -H "Content-Type: image/jpeg" \
     --data-binary @selfie.jpg

Resposta padrão

{
  "count": 41,
  "files": [
    "nr_sam_20260425_03278_414927.jpg",
    "nr_sam_20260425_02143_414927.jpg"
  ]
}

Informações adicionais (opcionais)

Parâmetros de query com =on. Nenhum deles quebra a resposta padrão de quem não os usa.

Filtrar por precisão — threshold

Diferente dos anteriores: leva um valor, não =on. Usa a mesma escala 0–100 em que confidence é devolvido, então quem vê "confidence": 87.4 e quer apenas resultados assim de seguros manda threshold=85. Filtra foto a foto pelo confidence de cada uma: threshold=93 devolve só fotos com confidence ≥ 93.0, e o count já vem filtrado.

POST /v1/partner/events/{evento}/search?dict=on&confidence=on&threshold=85

Como confidence é calculado

Para cada selfie avaliamos até 25 rostos candidatos do acervo, cada um com sua própria confiança. Cada candidato é resolvido para o grupo de fotos da pessoa a que pertence, ficando a melhor confiança de cada grupo; todos os grupos acima do limiar do evento entram no resultado. Cada foto pertence a um desses grupos e herda a confiança dele — por isso o valor varia dentro de um mesmo resultado, e não é um número único da busca.

Exemplo com todos os campos

POST /v1/partner/events/{evento}/search?dict=on&bbox=on&size=on&relevant=on&emotion=on&headpose=on&quality=on&age=on&gender=on&confidence=on

{
  "gender": "male",
  "age_group": "30-39",
  "underage_risk": false,
  "count": 41,
  "files": [
    {
      "file":             "nr_sam_20260425_03278_414927.jpg",
      "relevant_persons": 3,
      "relevance":        1.0,
      "confidence":       87.4,
      "quality":          93.1,
      "emotion":          "positive",
      "headpose":         { "yaw": -4.2, "pitch": 2.8, "roll": 1.1 },
      "face":             { "x": 812, "y": 340, "width": 220, "height": 260 },
      "image":            { "width": 4000, "height": 6000 }
    }
  ]
}

2 · Rostos de uma foto

Dado o nome de um arquivo do acervo, devolve todos os rostos daquela foto — não apenas o de uma pessoa. Útil para montar legendas, escolher fotos de destaque ou avaliar o enquadramento antes de publicar. Não envolve selfie nem busca.

Requisição

O nome do arquivo vai como parâmetro de query file — e não no caminho da URL — porque nomes de arquivo do acervo podem conter barras. Aceitamos tanto o nome completo devolvido pela busca (252670/nr_sam_….jpg) quanto apenas o nome base (nr_sam_….jpg).

curl -G https://busca.framematcher.com/v1/partner/events/{evento}/faces \
     -H "X-API-Key: SUA_CHAVE" \
     --data-urlencode "file=nr_sam_20260425_03278_414927.jpg"

Resposta

Os rostos vêm do mais relevante para o menos relevante.

{
  "file":  "252670/nr_sam_20260425_03278_414927.jpg",
  "image": { "width": 4000, "height": 6000 },
  "count": 2,
  "faces": [
    {
      "relevance":     1.0,
      "gender":        "male",
      "age_group":     "30-39",
      "underage_risk": false,
      "quality":       93.1,
      "emotion":       "positive",
      "headpose":      { "yaw": -4.2, "pitch": 2.8, "roll": 1.1 },
      "bbox":          { "x": 812, "y": 340, "width": 220, "height": 260 }
    },
    {
      "relevance":     0.636,
      "gender":        "female",
      "age_group":     "13-18",
      "underage_risk": true,
      "quality":       71.8,
      "emotion":       "neutral",
      "headpose":      { "yaw": 18.5, "pitch": -3.0, "roll": 0.4 },
      "bbox":          { "x": 1850, "y": 520, "width": 140, "height": 165 }
    }
  ]
}

Atributos

Faixa etária

As duas primeiras faixas não são décadas: elas acompanham os limites que importam juridicamente (18 anos e, dentro disso, 13 anos).

Proteção a menores — underage_risk

A estimativa de idade por foto é ruidosa. Uma pessoa menor de idade pode ser estimada acima de 18 em algumas fotos e, na média, cair numa faixa adulta. Como classificar um menor como adulto é o erro caro para quem opera sob regras de proteção a menores, a regra é deliberadamente assimétrica:

• Se duas ou mais fotos da pessoa estimam idade abaixo de 18 — ou 15% ou mais das fotos dela —, a pessoa é reportada numa faixa de menor (0-12 ou 13-18) mesmo que a média seja maior.
• underage_risk: true acompanha esses casos, e também qualquer pessoa cuja faixa já seja de menor.
• A regra só move alguém para dentro de uma faixa de menor, nunca para fora.

Emoção

positive (feliz, surpreso), negative (triste, bravo, com medo, com nojo) ou neutral.

Pose da cabeça — headpose

Três ângulos em graus. 0 em todos significa rosto frontal.

• yaw — giro horizontal (olhando para os lados).
• pitch — inclinação vertical (olhando para cima ou para baixo).
• roll — rotação no plano da foto (cabeça tombada para o ombro).

Qualidade, confiança e relevância

quality e confidence vão de 0.0 a 100.0, com uma casa decimal; relevance vai de 0 a 1. São três perguntas diferentes sobre a mesma foto:

• quality — o rosto saiu bem? (nitidez, iluminação, enquadramento)
• confidence — é mesmo a pessoa da selfie?
• relevance — a pessoa é o assunto da foto ou está ao fundo?

Códigos de resposta

Erros trazem sempre o mesmo formato:

{ "errors": [ { "code": "forbidden", "message": "missing api key" } ] }

Privacidade e retenção

• A selfie não é armazenada. É processada em memória e descartada ao fim da requisição — retenção zero, nenhum dado biométrico da selfie persiste.
• A resposta traz nomes de arquivo e atributos — nunca as imagens do acervo nem miniaturas.
• Os atributos descrevem rostos já presentes no acervo do evento, sob a base legal e o aviso de privacidade do organizador.
• Direitos do titular (incluindo exclusão) são atendidos pelo organizador do evento; fale conosco para acionar o processo.