> ## 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. # Correspondência facial 1:1: API Face Match > API Didit para comparação facial 1:1 via POST /v3/face-match/. Verificação de identidade, controlo de acesso e reautenticação, sem mínimos mensais. ## OpenAPI ````yaml pt/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 faciais (1:1) e obtenha uma pontuação (`score`) de similaridade (0–100), bem como um `status` `Approved`/`Declined`. **Como funciona.** Ambas as imagens são descodificadas e analisadas por um modelo biométrico (defina `rotate_image=true` se as capturas puderem estar de lado ou de cabeça para baixo); em seguida, é calculada uma pontuação de similaridade entre os dois rostos. Uma pontuação **estritamente superior** a `face_match_score_decline_threshold` (por predefinição `30`) devolve `status: "Approved"`; uma pontuação igual ou inferior devolve `Declined` com um aviso `LOW_FACE_MATCH_SIMILARITY`. Se não for de todo possível pontuar um par de rostos, a chamada continua a devolver `200` com `status: "Declined"` e um aviso `NO_REFERENCE_IMAGE` — `score` é `null` no caminho predefinido de gravação ou `0` com `save_api_request=false`. Envie um rosto nítido e virado para a frente por imagem para obter os melhores resultados. **Faturação.** Cada resposta `200` consome um crédito de API de Correspondência facial (pago a partir do crédito do seu plano ou do saldo de carregamento). Quando o saldo da organização não for suficiente para cobrir a chamada, o endpoint devolve `403` com o erro de créditos insuficientes antes de qualquer processamento de imagem. **Persistência de sessão (`save_api_request`, por predefinição `true`).** Quando for `true`, a chamada é persistida como uma sessão do tipo API: surge na Business Console, o `request_id` devolvido é um ID de sessão real que pode transmitir a `GET /v3/session/{sessionId}/decision/`, ambas as imagens são guardadas como as imagens de origem/destino de correspondência facial da sessão e é emitido um webhook `status.updated` para os endpoints de webhook que configurou. Quando for `false`, nada é guardado e `request_id` é um UUID de correlação único que não pode ser consultado mais tarde. **Índice de pesquisa facial.** Este endpoint nunca regista rostos no seu índice de pesquisa facial e nunca executa triagem de lista de bloqueio ou de duplicados — utilize `POST /v3/passive-liveness/` ou `POST /v3/face-search/` para essas operações. **Sandbox.** As chaves de API de sandbox ignoram todo o processamento e faturação: após a validação do pedido (dados de entrada mal formatados continuam a devolver `400`), o endpoint devolve um payload simulado estático com `Approved`, nenhuma sessão é persistida e não são consumidos créditos. **Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais em falta ou inválidas devolvem `403` (`{"detail": "You do not have permission to perform this action."}`) — esta API nunca devolve `401`. **Limite de pedidos.** Limite partilhado de escrita de 300 pedidos/min por chave de API em todos os endpoints POST/PATCH/DELETE; exceder este limite devolve `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 facial ao vivo ou candidata a verificar (por exemplo, uma selfie). Envie uma única fotografia frontal com o rosto do sujeito claramente visível e bem iluminado. Extensões permitidas: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Tamanho máximo de carregamento: **5 MB** (ficheiros maiores são rejeitados com `400`). As imagens são comprimidas automaticamente para ~0.5 MB antes do processamento, pelo que resoluções muito elevadas não melhoram a precisão. ref_image: type: string format: binary description: >- Imagem facial de referência para comparação (por exemplo, a fotografia de um documento de identificação ou uma fotografia registada anteriormente). O mesmo formato e limites de tamanho que `user_image`. face_match_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Limiar de semelhança (0–100) que orienta o `status` da resposta. Uma pontuação calculada **igual ou inferior** a este valor define o `status` como `Declined` e adiciona um aviso `LOW_FACE_MATCH_SIMILARITY`; uma pontuação estritamente superior devolve `Approved`. O valor predefinido de `30` é permissivo — aumente-o (por exemplo, `50`–`60`) para uma verificação mais rigorosa. Valores fora de 0–100 devolvem `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 utiliza a orientação que produzir a melhor deteção facial — útil para capturas móveis sem orientação EXIF. Adiciona latência, pelo que só deve ativá-lo se não puder garantir imagens na orientação correta. example: false save_api_request: type: boolean default: true description: >- Quando for `true` (predefinição), persiste a chamada como uma sessão do tipo API — visível na Business Console, recuperável através de `GET /v3/session/{sessionId}/decision/` utilizando o `request_id` devolvido e anunciada através de um webhook `status.updated`. Quando for `false`, nada é armazenado e `request_id` é um UUID transitório apenas para correlação de respostas. example: true vendor_data: type: string description: >- String opaca opcional (o seu ID de utilizador interno, e-mail, UUID...) guardada na sessão persistida e devolvida na resposta. Utilize-a para correlacionar chamadas de API com os seus próprios registos e para filtrar sessões mais tarde. 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 pedidos multipart, envie-o como um campo de texto codificado em JSON (por exemplo, `metadata={"flow":"login"}`) — é convertido num 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 número de ponto flutuante de 0–100 (duas casas decimais); `status` é `Approved` quando a pontuação está estritamente acima de `face_match_score_decline_threshold`, caso contrário é `Declined` com um aviso explicativo. Um par de baixa semelhança ou sem pontuação ainda devolve `200` — inspecione `face_match.status` e `face_match.warnings`, e não apenas o código HTTP. Quando `save_api_request=true`, `request_id` é o id de sessão persistido. 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 for estritamente superior a `face_match_score_decline_threshold` e tenha sido possível calcular uma pontuação; caso contrário, `Declined` (um aviso explica o motivo). score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Pontuação de semelhança de 0 a 100 — a confiança do modelo de que ambas as imagens representam a mesma pessoa. Arredondada a duas casas decimais apenas quando `save_api_request` for true; com `save_api_request=false`, é devolvido o float não formatado. `null` quando nenhum par de rostos pôde ser pontuado (com a predefinição `save_api_request=true`); com `save_api_request=false`, a mesma condição pode surgir como `score: 0`. Em qualquer dos casos, um aviso `NO_REFERENCE_IMAGE` está presente e o `status` é `Declined`. example: 99.41 user_image: type: object description: >- Resultados da deteçã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 detetado como coordenadas de píxeis `[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 deteção facial (0–1). example: 0.732973 age: type: number format: float description: >- Idade estimada pelo modelo para o rosto detetado, em anos. Apenas informativa — não afeta a decisão de correspondência facial. example: 26.91 gender: type: string description: >- Género previsto pelo modelo para o rosto detetado (`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 detetado. best_angle: type: integer description: >- Rotação (graus: 0, 90, 180 ou 270) que produziu a melhor deteção facial. Diferente de zero apenas quando `rotate_image=true` corrigiu a orientação. example: 0 ref_image: type: object description: >- Resultados da deteção facial para a imagem de referência, com o mesmo formato que `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 detetado como coordenadas de píxeis `[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 deteção facial (0–1). example: 0.732973 age: type: number format: float description: >- Idade estimada pelo modelo para o rosto detetado, em anos. Apenas informativa — não afeta a decisão de correspondência facial. example: 26.91 gender: type: string description: >- Género previsto pelo modelo para o rosto detetado (`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 detetado. best_angle: type: integer example: 0 warnings: type: array description: >- Vazio numa aprovação limpa. `NO_REFERENCE_IMAGE` (`error`) — não foi possível pontuar nenhum par de faces; `LOW_FACE_MATCH_SIMILARITY` (`error`) — pontuação igual ou inferior ao limiar de recusa. Qualquer um destes 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: >- Funcionalidade que gerou 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: >- Gravidade. Os avisos `error` alteram o `status` para `Declined`; as entradas `warning` e `information` são informativas e nunca recusam por si sós. short_description: type: string description: >- Resumo de uma linha legível por humanos sobre o risco. long_description: type: string description: Explicação legível do risco. vendor_data: type: string nullable: true description: Eco do `vendor_data` que enviou, ou `null`. metadata: type: object nullable: true additionalProperties: true description: Eco do objeto `metadata` que enviou, ou `null`. created_at: type: string format: date-time description: >- Carimbo de data/hora ISO 8601 (UTC) de quando a resposta foi gerada, por exemplo `2026-06-12T01:04:42.763237+00:00`. '400': description: >- Erro de validação. Devolvido quando uma imagem obrigatória está em falta, excede 5 MB, tem uma extensão não suportada ou quando uma opção está fora do intervalo. O corpo é o envelope padrão de erro de campo do DRF: um array de mensagens por campo afetado. content: application/json: examples: Missing required image: summary: >- `ref_image` (ou `user_image`) não incluído nos dados do formulário value: ref_image: - No file was submitted. Unsupported file extension: summary: Extensão de ficheiro 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 carregamento 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 de 0–100' value: face_match_score_decline_threshold: - Ensure this value is less than or equal to 100. '403': description: >- Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta e também quando o saldo da organização que efetua a chamada não consegue cobrir a chamada; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{"detail": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. A insuficiência de créditos devolve `403` com `{"error": ...}` antes de qualquer processamento de imagens ocorrer. content: application/json: examples: Missing or invalid API key: summary: Sem 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 pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). 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 pedidos 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: >- A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, 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á incorreta, 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 o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.