> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # API de comparação facial 1:1 (Face Match) > Didit Face Match: POST /v3/face-match/ compara rostos 1:1 em menos de 2s. Para verificação de identidade e controle de acesso, pagamento por uso. ## OpenAPI ````yaml pt-br/openapi-25.json POST /v3/face-match/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificação de identidade. Autentique-se com o cabeçalho x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/face-match/: post: tags: - Standalone APIs summary: Correspondência facial description: >- Compare duas imagens de rosto (1:1) e receba uma `score` de similaridade (0–100) e um `status` `Approved`/`Declined`. **Como funciona.** As duas imagens são decodificadas e analisadas por um modelo biométrico (defina `rotate_image=true` se as capturas puderem estar de lado ou de cabeça para baixo) e, em seguida, é calculada uma pontuação de similaridade entre os dois rostos. Uma pontuação **estritamente acima** de `face_match_score_decline_threshold` (padrão `30`) retorna `status: "Approved"`; uma pontuação igual ou inferior a esse valor retorna `Declined` com um aviso `LOW_FACE_MATCH_SIMILARITY`. Se nenhum par de rostos puder ser pontuado, a chamada ainda retorna `200` com `status: "Declined"` e um aviso `NO_REFERENCE_IMAGE`: `score` é `null` no fluxo padrão de salvamento, ou `0` com `save_api_request=false`. Envie um único rosto nítido e frontal por imagem para obter os melhores resultados. **Faturamento.** Cada resposta `200` consome um crédito da API de Correspondência facial (pago com o crédito do seu plano ou com o saldo recarregado). Quando o saldo da organização não cobre a chamada, o endpoint retorna `403` com o erro de créditos insuficientes antes de qualquer processamento de imagem. **Persistência da sessão (`save_api_request`, padrão `true`).** Quando `true`, a chamada é persistida como uma sessão do tipo API: ela aparece no Business Console, o `request_id` retornado é um ID de sessão real que você pode passar para `GET /v3/session/{sessionId}/decision/`, as duas imagens são armazenadas como imagens de origem/destino da correspondência facial da sessão e um webhook `status.updated` é emitido para os endpoints de webhook configurados. Quando `false`, nada é armazenado e `request_id` é um UUID de correlação avulso que não pode ser consultado depois. **Índice de busca facial.** Este endpoint nunca cadastra rostos no seu índice de busca facial e nunca executa triagem de lista de bloqueio ou de duplicados; para isso, use `POST /v3/passive-liveness/` ou `POST /v3/face-search/`. **Sandbox.** Chaves de API de sandbox ignoram todo o processamento e o faturamento: após a validação da requisição (entradas malformadas ainda retornam `400`), o endpoint retorna um payload simulado estático `Approved`, nenhuma sessão é persistida e nenhum crédito é consumido. **Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais ausentes ou inválidas retornam `403` (`{"detail": "You do not have permission to perform this action."}`); esta API nunca retorna `401`. **Limite de requisições.** Cota de escrita compartilhada de 300 requisições/min por chave de API entre todos os endpoints POST/PATCH/DELETE; ao excedê-la, a resposta é `429`. operationId: post_v3face-match parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image - ref_image properties: user_image: type: string format: binary description: >- Imagem de rosto ao vivo ou candidata a verificar (por exemplo, uma selfie). Envie uma única foto frontal com o rosto da pessoa claramente visível e bem iluminado. Extensões permitidas: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Tamanho máximo de upload: **5 MB** (arquivos maiores são rejeitados com `400`). As imagens são compactadas automaticamente para cerca de 0,5 MB antes do processamento, portanto resoluções muito altas não melhoram a precisão. ref_image: type: string format: binary description: >- Imagem facial de referência para comparação (por exemplo, o retrato de um documento de identidade ou uma foto cadastrada anteriormente). Mesmos limites de formato e tamanho de `user_image`. face_match_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Limiar de similaridade (0–100) que determina o `status` da resposta. Uma pontuação calculada **igual ou inferior** a esse valor define `status` como `Declined` e adiciona um aviso `LOW_FACE_MATCH_SIMILARITY`; uma pontuação estritamente superior retorna `Approved`. O padrão `30` é permissivo: aumente-o (por exemplo, `50`–`60`) para uma verificação mais rigorosa. Valores fora de 0–100 retornam `400`. example: 50 rotate_image: type: boolean default: false description: >- Quando `true`, o serviço testa as imagens de entrada em incrementos de 90 graus (0, 90, 180, 270) e usa a orientação que produz a melhor detecção de rosto, o que é útil para capturas móveis sem orientação EXIF. Aumenta a latência, então ative apenas se você não puder garantir imagens na posição vertical. example: false save_api_request: type: boolean default: true description: >- Quando `true` (padrão), persiste a chamada como uma sessão do tipo API: visível no Business Console, recuperável via `GET /v3/session/{sessionId}/decision/` usando o `request_id` retornado e anunciada por meio de um webhook `status.updated`. Quando `false`, nada é armazenado e `request_id` é um UUID transitório usado apenas para correlacionar a resposta. example: true vendor_data: type: string description: >- String opaca opcional (seu ID interno de usuário, e-mail, UUID…) armazenada na sessão persistida e devolvida na resposta. Use-a para correlacionar chamadas de API com seus próprios registros e para filtrar sessões posteriormente. example: user-123 metadata: type: object additionalProperties: true description: >- Objeto JSON opcional armazenado com a sessão (quando `save_api_request=true`) e devolvido na resposta. Em requisições multipart, envie-o como um campo de string codificada em JSON (por exemplo, `metadata={"flow":"login"}`), que é convertido em um objeto. example: flow: login device_id: abc123 example: user_image: (binary JPEG/PNG of the live selfie) ref_image: (binary JPEG/PNG of the reference photo) face_match_score_decline_threshold: 50 rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: login responses: '200': description: >- Correspondência facial calculada. `face_match.score` é um float de 0 a 100 (duas casas decimais); `status` é `Approved` quando a pontuação está estritamente acima de `face_match_score_decline_threshold` e, caso contrário, `Declined` com um aviso explicativo. Uma similaridade baixa ou um par que não pode ser pontuado ainda retorna `200`: verifique `face_match.status` e `face_match.warnings`, não apenas o código HTTP. Quando `save_api_request=true`, `request_id` é o ID da sessão persistida. content: application/json: examples: Approved: summary: 'Mesma pessoa: pontuação acima do limiar' value: request_id: f9f5a777-8002-44c6-baaf-128bcfd6e226 face_match: status: Approved score: 99.41 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 ref_image: entities: - bbox: - 653 - 745 - 1691 - 2185 confidence: 0.722082 age: 27 gender: male race: null best_angle: 0 warnings: [] vendor_data: user-123 metadata: flow: login created_at: '2026-06-12T01:04:42.763237+00:00' Declined - low similarity: summary: Pontuação igual ou inferior ao limiar de recusa value: request_id: 7cdda24e-311a-46d3-a3bb-e5d9b564ce73 face_match: status: Declined score: 24.87 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 ref_image: entities: - bbox: - 156 - 234 - 679 - 898 confidence: 0.717775 age: 41.2 gender: male race: null best_angle: 0 warnings: - risk: LOW_FACE_MATCH_SIMILARITY feature: FACEMATCH additional_data: null log_type: error short_description: Low face match similarity long_description: >- The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch. vendor_data: user-123 metadata: null created_at: '2026-06-12T01:08:19.859116+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- ID da sessão persistida quando `save_api_request=true` (utilizável com `GET /v3/session/{sessionId}/decision/`); caso contrário, um UUID de correlação transitório. face_match: type: object properties: status: type: string enum: - Approved - Declined description: >- `Approved` quando a pontuação de similaridade está estritamente acima de `face_match_score_decline_threshold` e foi possível calcular uma pontuação; `Declined` caso contrário (um aviso explica o motivo). score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Pontuação de similaridade de 0 a 100: a confiança do modelo de que as duas imagens retratam a mesma pessoa. É arredondada para duas casas decimais somente quando `save_api_request` é true; com `save_api_request=false`, o float bruto é retornado. É `null` quando nenhum par de rostos pôde ser pontuado (com o padrão `save_api_request=true`); com `save_api_request=false`, a mesma condição pode aparecer como `score: 0`. Em ambos os casos, um aviso `NO_REFERENCE_IMAGE` está presente e `status` é `Declined`. example: 99.41 user_image: type: object description: >- Resultados da detecção facial para as imagens analisadas. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Caixa delimitadora do rosto detectado, como coordenadas em pixels `[x_min, y_min, x_max, y_max]` na imagem processada. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: Confiança da detecção facial (0–1). example: 0.732973 age: type: number format: float description: >- Idade do rosto detectado estimada pelo modelo, em anos. Apenas informativa: não afeta a decisão de correspondência facial. example: 26.91 gender: type: string description: >- Gênero do rosto detectado previsto pelo modelo (`male` ou `female`). Apenas informativo. example: male race: type: string nullable: true description: >- Campo reservado: sempre `null` nas respostas deste endpoint. example: null description: Uma entrada por rosto detectado. best_angle: type: integer description: >- Rotação (em graus: 0, 90, 180 ou 270) que produziu a melhor detecção de rosto. Só é diferente de zero quando `rotate_image=true` corrigiu a orientação. example: 0 ref_image: type: object description: >- Resultados da detecção facial para a imagem de referência, com o mesmo formato de `user_image`. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Caixa delimitadora do rosto detectado, como coordenadas em pixels `[x_min, y_min, x_max, y_max]` na imagem processada. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: Confiança da detecção facial (0–1). example: 0.732973 age: type: number format: float description: >- Idade do rosto detectado estimada pelo modelo, em anos. Apenas informativa: não afeta a decisão de correspondência facial. example: 26.91 gender: type: string description: >- Gênero do rosto detectado previsto pelo modelo (`male` ou `female`). Apenas informativo. example: male race: type: string nullable: true description: >- Campo reservado: sempre `null` nas respostas deste endpoint. example: null description: Uma entrada por rosto detectado. best_angle: type: integer example: 0 warnings: type: array description: >- Vazio em uma aprovação sem ressalvas. `NO_REFERENCE_IMAGE` (`error`): nenhum par de rostos pôde ser pontuado; `LOW_FACE_MATCH_SIMILARITY` (`error`): pontuação igual ou inferior ao limiar de recusa. Qualquer um deles define `status` como `Declined`. items: type: object properties: risk: type: string enum: - NO_REFERENCE_IMAGE - LOW_FACE_MATCH_SIMILARITY description: Código de risco legível por máquina. feature: type: string enum: - FACEMATCH description: >- Recurso que emitiu o aviso. Sempre `FACEMATCH` neste endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- Sempre `null` para avisos de correspondência facial. log_type: type: string enum: - error - warning - information description: >- Severidade. Avisos `error` levam o `status` para `Declined`; entradas `warning` e `information` são apenas informativas e nunca recusam a sessão por conta própria. short_description: type: string description: Resumo legível do risco em uma linha. long_description: type: string description: Explicação legível do risco. vendor_data: type: string nullable: true description: Eco do `vendor_data` que você enviou, ou `null`. metadata: type: object nullable: true additionalProperties: true description: Eco do objeto `metadata` que você enviou, ou `null`. created_at: type: string format: date-time description: >- Timestamp ISO 8601 (UTC) do momento em que a resposta foi gerada, por exemplo `2026-06-12T01:04:42.763237+00:00`. '400': description: >- Erro de validação. Retornado quando uma imagem obrigatória está ausente, excede 5 MB ou tem uma extensão não suportada, ou quando uma opção está fora do intervalo permitido. O corpo é o envelope padrão de erros de campo do DRF: um array de mensagens para cada campo com problema. content: application/json: examples: Missing required image: summary: >- `ref_image` (ou `user_image`) não foi incluído nos dados do formulário value: ref_image: - No file was submitted. Unsupported file extension: summary: Extensão de arquivo fora de tiff/jpg/jpeg/png/webp value: user_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp. File too large: summary: O upload excede o limite de 5 MB value: user_image: - File size should not exceed 5 MB Threshold out of range: summary: '`face_match_score_decline_threshold` fora do intervalo 0–100' value: face_match_score_decline_threshold: - Ensure this value is less than or equal to 100. '403': description: >- Permissão negada. Retornado quando o cabeçalho `x-api-key` está ausente e também quando o saldo da organização que faz a chamada não cobre a chamada; uma chave incorreta, revogada ou expirada retorna `401`. Uma chave ausente retorna `403` com `{"detail": ...}`; uma chave incorreta, revogada ou expirada retorna `401`. Créditos insuficientes retornam `403` com `{"error": ...}` antes de qualquer processamento da imagem. content: application/json: examples: Missing or invalid API key: summary: Nenhum cabeçalho `x-api-key`, ou a chave é inválida/revogada value: detail: You do not have permission to perform this action. Not enough credits: summary: O saldo da organização não cobre a chamada value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Limite de requisições excedido. Todos os endpoints POST/PATCH/DELETE compartilham uma cota de 300 requisições de escrita por minuto por chave de API. A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Mais de 300 requisições de escrita no minuto atual value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/face-match/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'ref_image=@./id_portrait.jpg' \ -F 'face_match_score_decline_threshold=50' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.face_match.compare( user_image=open("user_image.jpg", "rb"), ref_image=open("ref_image.jpg", "rb"), face_match_score_decline_threshold=50.0, rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "login"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.faceMatch.compare({ user_image: await fileFromPath("user_image.jpg"), ref_image: await fileFromPath("ref_image.jpg"), face_match_score_decline_threshold: 50.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "login" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FaceMatch.Compare(ctx, didit.FaceMatchCompareParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tRefImage: didit.FileFromPath(\"ref_image.jpg\"),\n\tFaceMatchScoreDeclineThreshold: didit.Float(50.0),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"login\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import java.util.Map; import me.didit.Didit; import me.didit.types.FaceMatchCompareParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.faceMatch().compare(FaceMatchCompareParams.builder() .userImage(Path.of("user_image.jpg")) .refImage(Path.of("ref_image.jpg")) .faceMatchScoreDeclineThreshold(50.0) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "login")) .build()); System.out.println(result); - lang: php label: PHP source: |- faceMatch->compare([ 'user_image' => File::fromPath('user_image.jpg'), 'ref_image' => File::fromPath('ref_image.jpg'), 'face_match_score_decline_threshold' => 50.0, 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'login'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.face_match.compare( user_image: Pathname("user_image.jpg"), ref_image: Pathname("ref_image.jpg"), face_match_score_decline_threshold: 50.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "login" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.FaceMatch.CompareAsync(new FaceMatchCompareParams { UserImage = FileUpload.FromPath("user_image.jpg"), RefImage = FileUpload.FromPath("ref_image.jpg"), FaceMatchScoreDeclineThreshold = 50.0, RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "login" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Chave de API da sua aplicação, em Developers -> API keys no Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter escopo restrito: nenhum acesso, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está errada, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que a requisição veio de um endereço fora da sua lista de IPs; 404 em uma rota de sessão significa que a sessão está fora dos fluxos ou status da chave. Uma chave sem acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave sem permissão de escrita em sessões recebe links e tokens de sessão como null. Consulte https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.