Integrar a API REST do Server

Chame primeiro GET /v1/health. Esse endpoint é sempre público e informa readiness e auth_enabled. Quando auth_enabled é true, todos os demais endpoints exigem Authorization: Bearer <api_key>. Com a autenticação desativada, omita completamente o header Authorization; não envie um header vazio. O primeiro bloco mostra exatamente a forma sem autenticação, e o segundo é para deployments autenticados.

A API usa JSON snake_case e multipart/form-data para imagens. Toda resposta contém um header UUID x-request-id, repetido como request_id nos bodies JSON. Sinais de detection e qualidade usam 0.0–1.0, mas recognition similarity é o cosseno bruto em [-1.0, 1.0], não uma probabilidade. threshold aceita o intervalo inclusivo [0.0, 1.0], tem padrão 0.4 e há correspondência quando similarity >= threshold.

Uma Collection é um banco isolado de identidades e também um contrato de deployment. Na criação, fixa model ID, version, bundle digest, embedding dimension, preprocessing version, detection profile e exact-search profile ativos. A embedding_contract_id retornada é opaca: copie-a para trusted external enrollment e nunca a construa.

Comece com threshold 0.4 e calibre-o em dados de validação representativos. Respostas da Collection expõem detection_revision e configurações efetivas de busca. Alterações posteriores no detection profile valem para novas requests, sem reextrair FaceSamples existentes. Os perfis fazem busca plana exaustiva; precisões menores aproximam o cosseno FP32, mas não são índices ANN.

O cadastro usa multipart e aceita várias imagens numa request. review_mode=off segue a seleção facial da Collection; standard exige exatamente um rosto utilizável e aplica verificações configuradas de tamanho, confiança, qualidade e pose; strict acrescenta comparação de similaridade dentro e fora da pessoa. Um lote pode ter sucesso parcial com HTTP 201, então examine faces e rejected_images.

Search seleciona um query face com o perfil da Collection, compara com todo FaceSample ativo e atribui a cada Pessoa sua maior pontuação de amostra. Só resultados no ou acima do threshold efetivo são retornados, em similarity decrescente. Valide com uma imagem diferente das usadas no cadastro.

Detect retorna todos os rostos utilizáveis por área decrescente, com caixas em pixel e normalizadas, cinco landmarks, confiança do detector e sinais locais de qualidade. Não retorna embeddings nem persiste dados. Passe collection_id para usar o detection profile da Collection em vez do perfil imutável do sistema.

Compare seleciona um rosto de source e target, calcula a similarity de cosseno bruta e retorna matched segundo o threshold efetivo. Similarity pode ser negativa e nunca deve ser exibida como percentual de confiança. Se uma imagem não tiver rosto utilizável, retorna 422 face_not_found.

Instale o client diretamente deste checkout. Ele usa httpx, não contém inference runtime e aceita caminhos, bytes ou objetos binários semelhantes a arquivo. O timeout padrão de 65 segundos é ligeiramente maior que o deadline de 60 segundos do Server.

O exemplo usa o endereço CPU do User Guide na porta 18097 e um Server autenticado. Se a autenticação estiver desativada, construa Client("http://localhost:18097") sem api_key para não enviar Authorization header. O mesmo client também oferece create_monitor, update_monitor, monitor_state e monitor_events com cursor.

Erros usam um envelope JSON único com error.code, error.message, details opcionais e request_id. Mapeamentos comuns: 400 parâmetros inválidos, 401 key ausente/inválida, 404 recurso ausente, 409 conflito de estado/modelo, 413 limite de tamanho, 422 imagem inválida ou rosto inutilizável, 500 erro inesperado e 503 timeout ou runtime/índice indisponível.

GET pode ser repetido com segurança. Repita 429 e 503 transitórios com exponential backoff limitado e jitter; um 4xx de validação exige alterar a request. Após falha de transporte, a criação de Person/FaceSample é ambígua: leia primeiro o ID fornecido pelo client. Se um 503 de cadastro trouxer write_committed: true, a gravação já está em SQLite. Não repita às cegas; leia a Pessoa antes de decidir.

Um Monitor é uma tarefa server-side de reconhecimento RTSP cuja configuração fica em SQLite. Uma tarefa enabled retoma após reiniciar o Server e continua ao fechar o navegador. O decoder preserva apenas o frame mais novo; inferência lenta reduz a frequência efetiva em vez de acumular atraso. match_threshold: null herda o threshold da Collection.

A preview fica deliberadamente desativada por padrão e o reconhecimento independe dela. Quando habilitada, /preview.mjpeg transmite frames JPEG brutos sem anotação; o client desenha caixas com /state. Nunca coloque a API key na URL de preview. Consulte /events com seu cursor opaco para eventos enter, exit, error e recovery e trate truncated e stream_reset explicitamente.

Persista /data, monte /models como somente leitura e faça backup do SQLite junto do crop storage configurado com gravações paradas ou snapshot seguro para SQLite. Trate volume e cópias como dados biométricos. Termine HTTPS num reverse proxy confiável, permita apenas origins CORS necessários e aplique limites de taxa, body e tempo na borda. Nunca exponha uma avaliação sem autenticação.

O código-fonte do Server e o SDK Python usam MIT; os modelos estão expressamente fora dessa licença. A imagem do container não contém modelos. O instalador mostra a model license e verify confere identidade do pacote, licença assinada, validade e autorização. Pacotes públicos InsightFace, inclusive buffalo_l, normalmente se limitam a pesquisa acadêmica não comercial sem uma licença comercial separada.