API REST da FACEIO

Chame a API REST da FACEIO no seu backend privado para gerenciar Facial IDs, comparar imagens faciais, estimar idade e gênero, atualizar payloads e PIN Codes, consultar estatísticas e verificar o status da API.

ABRIR CONSOLE FACEIO

Crie uma aplicação no FACEIO Console e obtenha a chave privada da API no Application Manager. Mantenha a chave no backend.

A API REST da FACEIO

Endpoints HTTP de backend para gerenciamento de Facial ID, verificação facial e operações da aplicação

Cada aplicação FACEIO recebe automaticamente uma chave de API. Você pode recuperar essa chave no Gerenciador de aplicações do Console FACEIO ↗. Essa chave de API privada permite que seu backend chame a API REST da FACEIO a partir de qualquer linguagem de programação compatível com HTTPS.

  • Usa os recursos HTTP padrão para passar parâmetros e autenticar com uma chave de API.
  • Retorna códigos de resposta HTTP padrão para indicar estados de sucesso e erro.
  • Sempre retorna JSON em todas as requisições, independentemente do resultado.

Aviso importante

As chamadas de API e a instanciação do widget por meio da biblioteca JavaScript fio.js são fluxos separados. O cadastro e a autenticação acontecem no lado do cliente, no navegador do usuário. As chamadas à API REST devem partir do backend privado da sua aplicação e podem estar sujeitas a cotas ou limitação de taxa conforme o seu plano. Se você está começando com a FACEIO, comece por Primeiros passos, depois use o Guia de integração. Consulte a tabela de preços para conhecer os limites de cota da API REST.

URL base da API REST

  • O endpoint base da API da FACEIO está em https://api.faceio.net/.
  • O esquema da URL da requisição é https://api.faceio.net/cmd?param=val&param2=val2, em que cmd identifica o endpoint da API e os pares param=val representam seus parâmetros. Cada seção abaixo informa o método HTTP compatível.
  • Monitore a integridade e o status da API em tempo real em status.faceio.net ↗.
Resumo da API
URL base api.faceio.net
Endpoint de verificação de integridade api.faceio.net/status ↗
Arquitetura RESTful
Versões de HTTP e TLS HTTP/1.1, HTTP/2, HTTP/3; TLS 1.2 e 1.3
Autenticação Baseada em chave ↓
Rede Cloudflare
Tipo MIME da resposta HTTP application/json
Códigos de status HTTP Veja abaixo ↓

Recupere sua chave de API

Ao criar uma nova aplicação FACEIO, ela recebe automaticamente uma chave de API. Siga estas etapas para recuperar e gerenciar sua chave:

  1. 1 Faça login no Console FACEIO ↗.
  2. 2 Navegue até o Gerenciador de aplicações.
  3. 3 Selecione a aplicação que deseja gerenciar.
  4. 4 Clique na aba Chave de API.
  5. ✓ Copie a chave de API para as chamadas HTTP do servidor. A mesma aba mostra estatísticas e informações de cota da API.

Autenticação

Você autentica no endpoint da API FACEIO ao inserir sua chave de API na requisição HTTP recebida. Consulte a seção acima para saber como recuperar e gerenciar esta chave de API.

Métodos de autenticação

Envie a chave de API usando um dos métodos compatíveis a seguir:

Cabeçalho HTTP

Inclua sua chave de API no WWW-Authenticate cabeçalho HTTP:

WWW-Authenticate: Bearer API_KEY
Parâmetro de consulta

Ou acrescente a chave à sua POST ou GET URL da requisição:

https://api.faceio.net/endpoint?param=val&key=API_KEY

Aviso de segurança: Mantenha suas chaves de API seguras. Nunca as exponha em código do cliente, repositórios públicos, JavaScript do navegador, pacotes de aplicações móveis, logs ou ferramentas de análise. Use apenas scripts autorizados no servidor e consulte o guia de boas práticas de segurança antes de usar em produção.

Respostas, status e códigos de erro HTTP

Os seguintes códigos de status HTTP são retornados para cada requisição. Todos os endpoints da API retornam application/json independentemente de sucesso ou falha. Trate as falhas explicitamente no backend antes de conceder acesso, atualizar registros de usuários ou confiar no estado de um Facial ID.

200 Sucesso. O endpoint da API executou a operação com êxito.
400 Requisição inválida. Normalmente indica a ausência de um parâmetro obrigatório.
401 Não autorizado. Chave de API ausente ou inválida.
404 Não encontrado. O item solicitado, por exemplo Facial ID) não existe.
405 Método não permitido. Este endpoint não trata o método HTTP informado.
429 Muitas requisições. O limite de taxa foi excedido. Consulte a tabela de preços para consultar os limites de cota.
500 Erro interno do servidor ou manutenção em andamento.

Documentação dos endpoints

DELETEFACIALID

GET
URL de acesso do endpoint https://api.faceio.net/deletefacialid
Descrição

Exclua um Facial ID e os dados de payload vinculados da sua aplicação FACEIO. A operação também instrui o mecanismo de reconhecimento facial selecionado a remover o hash biométrico associado.

O Facial ID é um identificador único (UUID) atribuído anonimamente a cada usuário cadastrado. O cadastro é realizado por uma chamada ao método enroll() da biblioteca fio.js executada no cliente.

Disponibilidade Todos os planos
Método HTTP GET

Parâmetros HTTP

Campo Tipo Obrigatório Descrição
key HEX String SIM A chave da API REST da sua aplicação.
fid String SIM O Facial ID que deseja excluir (purgar).

Resposta HTTP

application/json

Este endpoint da API sempre retorna um objeto JSON. Os campos a seguir são retornados:

Campo Tipo Descrição
status Integer Código de status HTTP padrão: 200 em caso de sucesso; caso contrário, um status de erro, como 401.
payload Boolean TRUE se o Facial ID e os dados foram totalmente removidos. FALSE caso contrário.
Exemplo de código para exclusão de Facial ID (Python)

CHECKFACIALID

GET
URL de acesso do endpoint https://api.faceio.net/checkfacialid
Descrição

Verifique se um Facial ID está cadastrado na aplicação FACEIO associada à chave de API fornecida.
Disponibilidade Somente planos pagos ou atualizados. Consulte a página de preços para mais detalhes.
Método HTTP GET

Parâmetros HTTP

Campo Tipo Obrigatório Descrição
key HEX String SIM A chave da API REST da sua aplicação.
fid String SIM O Facial ID a ser verificado.

Resposta HTTP

application/json

Este endpoint da API sempre retorna um objeto JSON. Os campos a seguir são retornados:

Campo Tipo Descrição
status Integer Código de status HTTP padrão: 200 em caso de sucesso; caso contrário, um status de erro.
valid Boolean TRUE se o Facial ID é válido e está registrado. FALSE caso contrário.
Exemplo de código para validação de Facial ID (Python)

FACE-VERIFY

POST
URL de acesso do endpoint https://api.faceio.net/faceverify
Descrição

Compare duas imagens faciais

O endpoint faceverify compara os rostos em duas imagens e retorna o resultado da correspondência e as pontuações de similaridade.

Envie uma imagem de origem e uma imagem de destino, cada uma com um único rosto. Não é necessário cadastro prévio na FACEIO. Seu backend deve decidir como interpretar as pontuações retornadas no próprio fluxo.

Nota de privacidade: O processamento ocorre na memória (RAM). As imagens são removidas imediatamente após a análise. Nenhum dado é registrado ou armazenado. Consulte as boas práticas de privacidade antes de adicionar a verificação facial aos fluxos de produção.
Disponibilidade Somente planos pagos ou atualizados. Consulte a página de preços para mais detalhes.
Método HTTP POST

Parâmetros HTTP

Campo Tipo Obrigatório Descrição
key HEX String SIM A chave da API REST da sua aplicação.
src Base64 | URL SIM A pessoa de origem imagem. Deve ser uma string codificada em Base64, no formato data URI, ou uma URL acessível publicamente. Garanta que apenas um único rosto esteja presente.
target Base64 | URL SIM A imagem de destino a ser comparada com a imagem de origem. Deve ser uma string codificada em Base64, no formato data URI, ou uma URL acessível publicamente.

Resposta HTTP

application/json

Este endpoint da API sempre retorna um objeto JSON. Os campos a seguir são retornados:

Campo Tipo Descrição
status Integer Código de status HTTP padrão: 200 em caso de sucesso; caso contrário, um status de erro.
same_person Boolean TRUE se os rostos de origem e destino pertencem à mesma pessoa. FALSE caso contrário.
dist Float Pontuação de similaridade por distância de 0 a 1. Um valor mais próximo de 1 indica maior probabilidade de os rostos pertencerem à mesma pessoa.
sim Float Pontuação de similaridade cosseno de 0 a 1. Quanto mais próximo de 1, maior a similaridade.
Exemplo de código Face Verify (Python)

AGE-CHECK

POST
URL de acesso do endpoint https://api.faceio.net/agecheck
Descrição

Estimativa de idade e gênero

O endpoint agecheck retorna estimativas de idade e gênero para o rosto em uma imagem. Não é necessário cadastro prévio na FACEIO. Trate a idade como uma aproximação, não como prova de identidade, idade exata ou decisão de elegibilidade legal.

Nota de privacidade: O processamento ocorre na memória (RAM). As imagens são removidas imediatamente após a análise. Nenhum dado é registrado ou armazenado. Consulte as boas práticas de privacidade antes de adicionar estimativas de idade e gênero a um fluxo de produção.
Disponibilidade Somente planos pagos ou atualizados. Consulte a página de preços para mais detalhes.
Método HTTP POST

Parâmetros HTTP

Campo Tipo Obrigatório Descrição
key HEX String SIM A chave da API REST da sua aplicação.
img Base64 | URL SIM A imagem de entrada que contém o rosto a ser analisado. Formato: data:{MIME_type};base64,{data} ou uma URL acessível publicamente.

Resposta HTTP

application/json

Este endpoint da API sempre retorna um objeto JSON. Os campos a seguir são retornados:

Campo Tipo Descrição
status Integer Código de status HTTP padrão: 200 em caso de sucesso; caso contrário, um status de erro.
age Integer Idade estimada da pessoa na imagem.
gender String Estimativa de gênero da pessoa na imagem.
Exemplo de estimativa de idade e gênero (Python)

SETFACIALIDPAYLOAD

POST
URL de acesso do endpoint https://api.faceio.net/setfacialidpayload
Descrição

Defina ou altere os dados de payload associados a um usuário inscrito específico por meio do seu Facial ID.

O payload armazenado é retornado ao seu site ou aplicativo web pelo fio.js após a próxima autenticação bem-sucedida do usuário. Use-o para dados mínimos da aplicação, como um ID interno de usuário. Não inclua segredos nem decisões de autorização no payload.
Disponibilidade Somente planos pagos ou atualizados. Consulte a página de preços para mais detalhes.
Método HTTP POST

Parâmetros HTTP

Campo Tipo Obrigatório Descrição
key HEX String SIM A chave da API REST da sua aplicação.
fid String SIM O Facial ID a ser atualizado.
payload String/Dados brutos SIM Os novos dados de payload a serem associados ao Facial ID. Esses dados serão retornados durante autenticações futuras. Use strings, JSON ou outro formato de payload controlado pelo backend.

Resposta HTTP

application/json
Campo Tipo Descrição
status Integer Código de status HTTP padrão: 200 em caso de sucesso; caso contrário, um status de erro.
payload Boolean TRUE se o payload foi atualizado com sucesso. FALSE caso contrário.

SETFACIALIDPINCODE

POST
URL de acesso do endpoint https://api.faceio.net/setfacialidpincode
Descrição

Defina ou altere o código PIN associado a um usuário inscrito específico na sua aplicação FACEIO.
Disponibilidade Somente planos pagos ou atualizados. Consulte a página de preços para mais detalhes.
Método HTTP POST

Parâmetros HTTP

Campo Tipo Obrigatório Descrição
key HEX String SIM A chave da API REST da sua aplicação.
fid String SIM O Facial ID a ser atualizado.
pin Number SIM O novo código PIN a ser associado ao Facial ID. O usuário deverá confirmar esse PIN quando solicitado durante uma autenticação futura. O PIN deve conter no mínimo 4 e no máximo 16 dígitos.

Resposta HTTP

application/json

Este endpoint da API sempre retorna um objeto JSON. Os campos a seguir são retornados:

Campo Tipo Descrição
status Integer Código de status HTTP padrão. 200 indica sucesso.
payload Boolean TRUE se o código PIN foi atualizado com sucesso. FALSE caso contrário.
Exemplo de código para alterar o PIN (Python)

STAT

GET
URL de acesso do endpoint https://api.faceio.net/stat
Descrição

Colete análises e estatísticas da sua aplicação FACEIO, incluindo o total de rostos indexados, chamadas de API e enrollments recentes. Observação: as estatísticas são armazenadas em cache e atualizadas a cada 5 minutos.
Disponibilidade Somente planos pagos ou atualizados. Consulte a página de preços para mais detalhes.
Método HTTP GET

Parâmetros HTTP

Campo Tipo Obrigatório Descrição
key HEX String SIM A chave da API REST da sua aplicação.

Resposta HTTP

application/json

Este endpoint da API sempre retorna um objeto JSON. Os campos a seguir são retornados:

Campo Tipo Descrição
status Integer Código de status HTTP padrão: 200 em caso de sucesso; caso contrário, um status de erro, como 401.
total_api_calls Integer Contagem acumulada de chamadas de API feitas por esta aplicação.
total_indexed_faces Integer Número total de rostos únicos atualmente inscritos/indexados.
last_indexed_faces Array Uma lista contendo os Facial IDs dos usuários inscritos mais recentemente.

ABOUT

GET
URL de acesso do endpoint https://api.faceio.net/about
Descrição

Recupere as informações de versão e o aviso de direitos autorais da instância da API FACEIO em execução.
Disponibilidade Todos os planos
Método HTTP GET

Parâmetros HTTP

Nenhum parâmetro é necessário.

Resposta HTTP

application/json
Campo Tipo Descrição
status Integer Código de status HTTP padrão: 200 em caso de sucesso; caso contrário, um status de erro.
payload String String de versão do servidor e aviso de direitos autorais.

STATUS

GET
URL de acesso do endpoint https://api.faceio.net/status
Descrição

Verifique o status de integridade dos servidores da API FACEIO. O histórico de status em tempo real também está disponível em status.faceio.net ↗.
Disponibilidade Todos os planos
Método HTTP GET

Parâmetros HTTP

Nenhum parâmetro é necessário.

Resposta HTTP

application/json
Campo Tipo Descrição
status Integer 200 indica status operacional (System OK). 500 indica manutenção ou interrupção do serviço.
error String Mensagem de erro, se o status for diferente de 200.
payload String Mensagem de status, por exemplo, "System OK".

Conecte seu backend à API REST

Crie uma aplicação FACEIO, obtenha a chave privada da REST API no Console e chame os endpoints documentados pelo backend. Nunca exponha a chave de API no navegador nem no código de um aplicativo móvel.

Leia o guia de primeiros passos → Abrir Console FACEIO
Precisão LFW de 99,7%