Comparação facial
curl --request POST \
--url https://api.lazydata.com.br/v1/validation/facial/compare \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"source_image": "<string>",
"target_image": "<string>",
"threshold": 123
}
'import requests
url = "https://api.lazydata.com.br/v1/validation/facial/compare"
payload = {
"source_image": "<string>",
"target_image": "<string>",
"threshold": 123
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({source_image: '<string>', target_image: '<string>', threshold: 123})
};
fetch('https://api.lazydata.com.br/v1/validation/facial/compare', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.lazydata.com.br/v1/validation/facial/compare",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'source_image' => '<string>',
'target_image' => '<string>',
'threshold' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.lazydata.com.br/v1/validation/facial/compare"
payload := strings.NewReader("{\n \"source_image\": \"<string>\",\n \"target_image\": \"<string>\",\n \"threshold\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.lazydata.com.br/v1/validation/facial/compare")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"source_image\": \"<string>\",\n \"target_image\": \"<string>\",\n \"threshold\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.lazydata.com.br/v1/validation/facial/compare")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"source_image\": \"<string>\",\n \"target_image\": \"<string>\",\n \"threshold\": 123\n}"
response = http.request(request)
puts response.read_body{
"code": 200,
"message": "Validação facial concluída com sucesso.",
"result": {
"id": "9fcb573b-7f62-4774-978b-07e89dfef5f2",
"status": "completed",
"test": false,
"cost": {
"total": 0.05,
"charged": 0.05,
"refunded": 0
},
"timing": {
"total": 1.24
},
"comparison": {
"matched": true,
"similarity": 97.42,
"confidence": 99.12,
"threshold": 80,
"source_face": {
"confidence": 99.9,
"bounding_box": {
"width": 0.15,
"height": 0.19,
"left": 0.38,
"top": 0.26
}
},
"target_face": {
"confidence": 99.7,
"bounding_box": {
"width": 0.16,
"height": 0.2,
"left": 0.37,
"top": 0.27
}
},
"unmatched_faces": 0
}
}
}
{
"code": 400,
"message": "Imagem inválida."
}
{
"code": 401,
"message": "Credencial da API inválida."
}
{
"code": 403,
"message": "A credencial da API não possui permissão para este recurso."
}
{
"code": 502,
"message": "Não foi possível consultar o provedor da validação."
}
Validações
Comparação facial
Compare duas imagens faciais e retorne similaridade, confiança, status e cobrança aplicada.
POST
https://api.lazydata.com.br/
/
v1
/
validation
/
facial
/
compare
Comparação facial
curl --request POST \
--url https://api.lazydata.com.br/v1/validation/facial/compare \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"source_image": "<string>",
"target_image": "<string>",
"threshold": 123
}
'import requests
url = "https://api.lazydata.com.br/v1/validation/facial/compare"
payload = {
"source_image": "<string>",
"target_image": "<string>",
"threshold": 123
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({source_image: '<string>', target_image: '<string>', threshold: 123})
};
fetch('https://api.lazydata.com.br/v1/validation/facial/compare', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.lazydata.com.br/v1/validation/facial/compare",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'source_image' => '<string>',
'target_image' => '<string>',
'threshold' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.lazydata.com.br/v1/validation/facial/compare"
payload := strings.NewReader("{\n \"source_image\": \"<string>\",\n \"target_image\": \"<string>\",\n \"threshold\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.lazydata.com.br/v1/validation/facial/compare")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"source_image\": \"<string>\",\n \"target_image\": \"<string>\",\n \"threshold\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.lazydata.com.br/v1/validation/facial/compare")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"source_image\": \"<string>\",\n \"target_image\": \"<string>\",\n \"threshold\": 123\n}"
response = http.request(request)
puts response.read_body{
"code": 200,
"message": "Validação facial concluída com sucesso.",
"result": {
"id": "9fcb573b-7f62-4774-978b-07e89dfef5f2",
"status": "completed",
"test": false,
"cost": {
"total": 0.05,
"charged": 0.05,
"refunded": 0
},
"timing": {
"total": 1.24
},
"comparison": {
"matched": true,
"similarity": 97.42,
"confidence": 99.12,
"threshold": 80,
"source_face": {
"confidence": 99.9,
"bounding_box": {
"width": 0.15,
"height": 0.19,
"left": 0.38,
"top": 0.26
}
},
"target_face": {
"confidence": 99.7,
"bounding_box": {
"width": 0.16,
"height": 0.2,
"left": 0.37,
"top": 0.27
}
},
"unmatched_faces": 0
}
}
}
{
"code": 400,
"message": "Imagem inválida."
}
{
"code": 401,
"message": "Credencial da API inválida."
}
{
"code": 403,
"message": "A credencial da API não possui permissão para este recurso."
}
{
"code": 502,
"message": "Não foi possível consultar o provedor da validação."
}
Executa uma comparação facial entre duas imagens e retorna se as faces atingiram a similaridade mínima configurada.
Use esta rota para validação de identidade, antifraude, onboarding, revisão cadastral e fluxos que precisam comparar uma imagem de referência com uma imagem enviada pelo usuário.
Estrutura de
Estrutura de
Estrutura de
Estrutura de
Estrutura de
Estrutura de
Em chamadas de teste,
{
"code": 200,
"message": "Validação facial concluída com sucesso.",
"result": {
"id": "9fcb573b-7f62-4774-978b-07e89dfef5f2",
"status": "completed",
"test": false,
"cost": {
"total": 0.05,
"charged": 0.05,
"refunded": 0
},
"timing": {
"total": 1.24
},
"comparison": {
"matched": true,
"similarity": 97.42,
"confidence": 99.12,
"threshold": 80,
"source_face": {
"confidence": 99.9,
"bounding_box": {
"width": 0.15,
"height": 0.19,
"left": 0.38,
"top": 0.26
}
},
"target_face": {
"confidence": 99.7,
"bounding_box": {
"width": 0.16,
"height": 0.2,
"left": 0.37,
"top": 0.27
}
},
"unmatched_faces": 0
}
}
}
{
"code": 400,
"message": "Imagem inválida."
}
{
"code": 401,
"message": "Credencial da API inválida."
}
{
"code": 403,
"message": "A credencial da API não possui permissão para este recurso."
}
{
"code": 502,
"message": "Não foi possível consultar o provedor da validação."
}
Corpo da requisição
string
required
Imagem base usada como referência na comparação. Aceita Base64 puro ou Data URL.
string
required
Imagem comparada com a imagem base. Aceita Base64 puro ou Data URL.
number
default:"80"
Similaridade mínima, de
0 a 100, para considerar as faces compatíveis.string
Use
sandbox para executar uma chamada de teste sem consumo de saldo.Para detalhes sobre chamadas de teste, consulte Ambiente de teste.
Exemplo de corpo
{
"source_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
"target_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
"threshold": 80
}
Regras das imagens
| Regra | Descrição |
|---|---|
| Formatos aceitos | JPG, PNG ou WebP. |
| Envio | Base64 puro ou Data URL com prefixo de MIME type. |
| Limite | Até 10 MB por imagem. |
| Face detectável | Cada imagem deve conter uma face detectável pelo provedor. |
| Qualidade | Imagens muito escuras, desfocadas, cortadas ou com múltiplas faces podem gerar falha ou baixa confiança. |
Resposta
integer
required
Código da resposta da API.
string
required
Mensagem descritiva da resposta.
object
required
Objeto principal com o identificador da validação, cobrança, tempo de execução e resultado da comparação.
Estrutura de result
| Campo | Tipo | Descrição |
|---|---|---|
id | string | Identificador único da validação. |
status | string | Status da execução. Para esta rota, normalmente completed. |
test | boolean | Indica se a chamada foi executada em ambiente de teste. |
cost | object | Valores cobrados ou estornados. |
timing | object | Tempo de execução em segundos. |
comparison | object | Resultado técnico da comparação facial. |
Estrutura de result.cost
| Campo | Tipo | Descrição |
|---|---|---|
total | number | Valor total da validação. |
charged | number | Valor debitado nesta chamada. Em sandbox, retorna 0. |
refunded | number | Valor estornado, quando houver. |
Estrutura de result.timing
| Campo | Tipo | Descrição |
|---|---|---|
total | number | Tempo total de execução em segundos. |
Estrutura de result.comparison
| Campo | Tipo | Descrição |
|---|---|---|
matched | boolean | Indica se a similaridade atingiu o threshold informado. |
similarity | number | Percentual de similaridade entre as faces comparadas. |
confidence | number | Menor confiança entre as faces usadas na comparação. |
threshold | number | Similaridade mínima usada na validação. |
source_face | object | Dados da face detectada na imagem base. |
target_face | object | Dados da face detectada na imagem comparada. |
unmatched_faces | integer | Quantidade de faces detectadas que não foram compatíveis. |
Estrutura de source_face e target_face
| Campo | Tipo | Descrição |
|---|---|---|
confidence | number | Confiança de detecção da face. |
bounding_box | object | Coordenadas proporcionais da face na imagem. |
Estrutura de bounding_box
| Campo | Tipo | Descrição |
|---|---|---|
width | number | Largura proporcional da face. |
height | number | Altura proporcional da face. |
left | number | Posição horizontal proporcional da face. |
top | number | Posição vertical proporcional da face. |
Ambiente de teste
Para executar uma chamada sem consumo de saldo, envie o header:x-ambient: sandbox
test retorna true e charged retorna 0.
Respostas esperadas
As respostas possíveis estão exemplificadas no painel lateral da página.| Status | Quando ocorre |
|---|---|
200 | Validação facial concluída com sucesso. |
400 | Imagem inválida, face não detectada ou threshold fora do intervalo permitido. |
401 | A chave da API está ausente, inválida ou não pôde ser autenticada. |
403 | A credencial não possui escopo de validação, o plano não permite acesso ou há bloqueio financeiro. |
422 | Validação do corpo da requisição falhou no schema da API reference. |
502 | Falha ao consultar o provedor da validação. |
Regras importantes
- A credencial usada precisa possuir o escopo de validação.
- O plano da conta precisa permitir API e validações.
- Chamadas reais debitam o valor da validação conforme o preço vigente da conta.
- Falhas de provedor ou face não detectada podem gerar estorno automático quando houver débito reservado.
- O campo
matcheddepende dothresholdinformado; aumentar o limite torna a aprovação mais rígida. - A comparação facial não executa validação documental; ela apenas compara as faces das imagens enviadas.

