> ## 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. # Coincidència facial API: comparació facial 1:1 > Didit: API de comparació facial 1:1 (POST /v3/face-match/) per a verificació d'identitat. Menys de 2s d'inferència, preu per ús, sense mínims. ## OpenAPI ````yaml ca/openapi-25.json POST /v3/face-match/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificació d'identitat. Autentica't amb la capçalera x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/face-match/: post: tags: - Standalone APIs summary: Coincidència facial description: >- Compara dues imatges facials (1:1) i obtén una puntuació de similitud `score` (0–100) més un estat `status` `Approved`/`Declined`. **Com funciona.** Ambdues imatges es descodifiquen i s'analitzen mitjançant un model biomètric (defineix `rotate_image=true` si les captures poden estar de costat o cap per avall), i després es calcula una puntuació de similitud entre les dues cares. Una puntuació **estrictament superior** a `face_match_score_decline_threshold` (per defecte `30`) retorna `status: "Approved"`; una puntuació igual o inferior retorna `Declined` amb una advertència `LOW_FACE_MATCH_SIMILARITY`. Si no es pot puntuar cap parell de cares, la crida continua retornant `200` amb `status: "Declined"` i una advertència `NO_REFERENCE_IMAGE` — `score` és `null` en la ruta de desat per defecte, o `0` amb `save_api_request=false`. Envia una sola cara frontal i nítida per imatge per obtenir els millors resultats. **Facturació.** Cada resposta `200` consumeix un crèdit de l'API de Coincidència facial (pagat des del crèdit del teu pla o saldo de recàrrega). Quan el saldo de l'organització no pot cobrir la crida, l'endpoint retorna `403` amb l'error de crèdits insuficients abans de processar cap imatge. **Persistència de la sessió (`save_api_request`, per defecte `true`).** Quan és `true`, la crida es desa com una sessió de tipus API: apareix a la Business Console, el `request_id` retornat és un identificador de sessió real que pots passar a `GET /v3/session/{sessionId}/decision/`, ambdues imatges s'emmagatzemen com a imatges d'origen i objectiu de coincidència facial de la sessió, i s'emet un webhook `status.updated` cap a les teves destinacions de webhook configurades. Quan és `false`, no s'emmagatzema res i `request_id` és un UUID de correlació puntual que no es podrà consultar més endavant. **Índex de cerca facial.** Aquest endpoint mai no inscriu cares al teu índex de cerca facial ni executa cribratge de llistes de bloqueig o duplicats — utilitza `POST /v3/passive-liveness/` o `POST /v3/face-search/` per a aquests casos. **Sandbox.** Les claus d'API de sandbox ometen tot el processament i la facturació: després de la validació de la sol·licitud (les entrades mal formades continuen retornant `400`), l'endpoint retorna un payload simulat estàtic `Approved`, no es desa cap sessió i no es consumeixen crèdits. **Autenticació.** Envia la clau d'API de la teva aplicació a la capçalera `x-api-key`. Unes credencials absents o no vàlides retornen `403` (`{"detail": "You do not have permission to perform this action."}`) — aquesta API mai no retorna `401`. **Límit de freqüència.** Quota compartida d'escriptura de 300 sol·licituds/min per clau d'API en tots els endpoints POST/PATCH/DELETE; superar-lo retorna `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: >- Imatge facial en viu o candidata a verificar (p. ex., una selfie). Envia una única fotografia frontal amb la cara del subjecte ben visible i ben il·luminada. Extensions permeses: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Mida màxima de pujada: **5 MB** (els fitxers més grans es rebutgen amb `400`). Les imatges es comprimeixen automàticament a ~0.5 MB abans de processar-les, per la qual cosa les resolucions molt altes no milloren la precisió. ref_image: type: string format: binary description: >- Imatge facial de referència amb la qual comparar (p. ex., la foto d'un document d'identitat o una foto registrada prèviament). Els mateixos límits de format i mida que `user_image`. face_match_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Llindar de similitud (0–100) que determina el valor de `status` a la resposta. Una puntuació calculada **igual o inferior** a aquest valor estableix `status` com a `Declined` i afegeix una advertència `LOW_FACE_MATCH_SIMILARITY`; una puntuació estrictament superior retorna `Approved`. El valor per defecte `30` és permissiu —augmenta'l (p. ex., `50`–`60`) per a una verificació més estricta. Els valors fora de 0–100 retornen `400`. example: 50 rotate_image: type: boolean default: false description: >- Quan és `true`, el servei prova les imatges d'entrada en increments de 90 graus (0, 90, 180, 270) i utilitza l'orientació que ofereix la millor detecció facial — útil per a captures mòbils a les quals falta l'orientació EXIF. Afegeix latència, de manera que activa'l només si no pots garantir imatges orientades correctament. example: false save_api_request: type: boolean default: true description: >- Quan és `true` (per defecte), manté la crida com una sessió de tipus API — visible a la Business Console, recuperable mitjançant `GET /v3/session/{sessionId}/decision/` utilitzant el `request_id` retornat i anunciada a través d'un webhook `status.updated`. Quan és `false`, no s'emmagatzema res i `request_id` és un UUID transitori només per a la correlació de la resposta. example: true vendor_data: type: string description: >- Cadena opaca opcional (el teu ID d'usuari intern, correu electrònic, UUID…) desada a la sessió persistent i retornada a la resposta. Utilitza-la per correlacionar crides a l'API amb els teus propis registres i per filtrar sessions més endavant. example: user-123 metadata: type: object additionalProperties: true description: >- Objecte JSON opcional emmagatzemat amb la sessió (quan `save_api_request=true`) i retornat a la resposta. En sol·licituds multipart, envia'l com a camp de cadena codificat en JSON (p. ex., `metadata={"flow":"login"}`); s'analitza com un objecte. 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: >- Coincidència facial calculada. `face_match.score` és un nombre flotant de 0 a 100 (dos decimals); `status` és `Approved` quan la puntuació està estrictament per sobre de `face_match_score_decline_threshold`, altrament `Declined` amb una advertència explicativa. Una similitud baixa o una parella no avaluable encara retorna `200` — inspecciona `face_match.status` i `face_match.warnings`, no només el codi HTTP. Quan `save_api_request=true`, `request_id` és l'identificador de sessió persistit. content: application/json: examples: Approved: summary: 'Mateixa persona: puntuació per sobre del llindar' 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: Puntuació igual o inferior al llindar de rebuig 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 de sessió persistida quan `save_api_request=true` (utilitzable amb `GET /v3/session/{sessionId}/decision/`); en cas contrari, un UUID de correlació transitori. face_match: type: object properties: status: type: string enum: - Approved - Declined description: >- `Approved` quan la puntuació de similitud és estrictament superior a `face_match_score_decline_threshold` i s'ha pogut calcular una puntuació; `Declined` en cas contrari (una advertència n'explica el motiu). score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Puntuació de similitud de 0 a 100 —la confiança del model que ambdues imatges representen la mateixa persona. Arrodonida a dos decimals només quan `save_api_request` és cert; amb `save_api_request=false` es retorna el nombre decimal en cru. `null` quan no s'ha pogut puntuar cap parell de cares (amb el valor per defecte `save_api_request=true`); amb `save_api_request=false` la mateixa condició es pot mostrar com a `score: 0`. En qualsevol cas, hi ha una advertència `NO_REFERENCE_IMAGE` present i `status` és `Declined`. example: 99.41 user_image: type: object description: >- Resultats de la detecció facial per a les imatges analitzades. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Quadre delimitador de la cara detectada com a coordenades de píxels `[x_min, y_min, x_max, y_max]` a la imatge processada. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: Confiança de la detecció facial (0–1). example: 0.732973 age: type: number format: float description: >- Edat estimada pel model de la cara detectada, en anys. Només informativa: no afecta la decisió de coincidència facial. example: 26.91 gender: type: string description: >- Gènere predit pel model de la cara detectada (`male` o `female`). Només informatiu. example: male race: type: string nullable: true description: >- Camp reservat: sempre `null` a les respostes d'aquest endpoint. example: null description: Una entrada per cara detectada. best_angle: type: integer description: >- Rotació (graus: 0, 90, 180 o 270) que ha produït la millor detecció facial. Només és diferent de zero quan `rotate_image=true` ha corregit l'orientació. example: 0 ref_image: type: object description: >- Resultats de la detecció facial per a la imatge de referència, amb la mateixa estructura que `user_image`. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Quadre delimitador de la cara detectada com a coordenades de píxels `[x_min, y_min, x_max, y_max]` a la imatge processada. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: Confiança de la detecció facial (0–1). example: 0.732973 age: type: number format: float description: >- Edat estimada pel model de la cara detectada, en anys. Només informativa: no afecta la decisió de coincidència facial. example: 26.91 gender: type: string description: >- Gènere predit pel model de la cara detectada (`male` o `female`). Només informatiu. example: male race: type: string nullable: true description: >- Camp reservat: sempre `null` a les respostes d'aquest endpoint. example: null description: Una entrada per cara detectada. best_angle: type: integer example: 0 warnings: type: array description: >- Buit en cas d'aprovació neta. `NO_REFERENCE_IMAGE` (`error`): no s'ha pogut puntuar cap parell de cares; `LOW_FACE_MATCH_SIMILARITY` (`error`): puntuació igual o inferior al llindar de rebuig. Qualsevol d'aquestes estableix `status` a `Declined`. items: type: object properties: risk: type: string enum: - NO_REFERENCE_IMAGE - LOW_FACE_MATCH_SIMILARITY description: Codi de risc llegible per màquina. feature: type: string enum: - FACEMATCH description: >- Funcionalitat que ha generat l'advertència. Sempre `FACEMATCH` en aquest endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- Sempre `null` per a les advertències de coincidència facial. log_type: type: string enum: - error - warning - information description: >- Gravetat. Les advertències `error` canvien `status` a `Declined`; les entrades `warning` i `information` són consultives i mai no rebutgen per si soles. short_description: type: string description: >- Resum d'una sola línia del risc, llegible per a humans. long_description: type: string description: Explicació fàcil de llegir del risc. vendor_data: type: string nullable: true description: Ressò de les `vendor_data` que has enviat, o `null`. metadata: type: object nullable: true additionalProperties: true description: Ressò de l'objecte `metadata` que has enviat, o `null`. created_at: type: string format: date-time description: >- Marca de temps ISO 8601 (UTC) de quan s'ha generat la resposta, p. ex. `2026-06-12T01:04:42.763237+00:00`. '400': description: >- Error de validació. Es retorna quan falta una imatge obligatòria, supera els 5 MB, té una extensió no admesa o quan una opció està fora de rang. El cos és l'embolcall estàndard d'errors de camp de DRF: una matriu de missatges per cada camp que conté l'error. content: application/json: examples: Missing required image: summary: >- `ref_image` (o `user_image`) no s'ha inclòs a les dades del formulari value: ref_image: - No file was submitted. Unsupported file extension: summary: Extensió de fitxer no permesa (només 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: La pujada supera el límit 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: >- Permís denegat. Es retorna quan falta la capçalera `x-api-key`, i també quan el saldo de l'organització que fa la crida no pot cobrir la crida; una clau incorrecta, revocada o caducada retorna `401`. Si falta la clau es retorna `403` amb `{"detail": ...}`; una clau incorrecta, revocada o caducada retorna `401`. La manca de crèdit retorna `403` amb `{"error": ...}` abans que es produeixi cap processament d'imatges. content: application/json: examples: Missing or invalid API key: summary: >- Sense capçalera `x-api-key`, o la clau no és vàlida/s'ha revocat value: detail: You do not have permission to perform this action. Not enough credits: summary: El saldo de l'organització no pot cobrir la crida value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- S'ha superat el límit de freqüència. Els endpoints POST/PATCH/DELETE comparteixen un pressupost de 300 sol·licituds d'escriptura per minut per clau d'API (la creació de transaccions i la ingesta d'esdeveniments tenen un pressupost independent de 600). La resposta inclou les capçaleres `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` i `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Més de 300 sol·licituds d'escriptura en el minut actual 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: >- La clau d'API de la teva aplicació, des de Developers -> API keys a la Business Console. La clau primària té accés complet. Una clau amb nom pot tenir l'abast limitat: cap, lectura o escriptura per recurs, limitada a determinats fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a una data de caducitat. 401 significa que la clau és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap clau, que la clau no té accés a aquest recurs o acció, o que la sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una ruta de sessió significa que la sessió està fora dels fluxos de treball o estats de la clau. Una clau sense accés a fitxers multimèdia rep els URL d'imatge, vídeo i PDF com a null, i una clau sense permís d'escriptura de sessions rep els enllaços de sessió i els tokens com a null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.