> ## 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 prova de vida passiva: detecció de deepfakes > Didit detecta màscares, impressions, rèpliques i deepfakes amb una imatge. Passiu, inferència sub-2s, preu per ús i sense mínims mensuals. ## OpenAPI ````yaml ca/openapi-25.json POST /v3/passive-liveness/ 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/passive-liveness/: post: tags: - Standalone APIs summary: Prova de vida passiva description: >- Detecta atacs de presentació (fotos impreses, reproduccions en pantalla, màscares, deepfakes) a partir d'una única imatge facial. No requereix vídeo, moviment ni interacció de l'usuari. **Com funciona.** La imatge és analitzada per un model biomètric; s'avalua la cara detectada més gran i es calcula una `score` de prova de vida (0–100). L'estat `status` és `Declined` quan s'activa qualsevol advertència de gravetat `error`: - `NO_FACE_DETECTED`: el model de prova de vida no ha trobat cap cara, - `LOW_LIVENESS_SCORE`: puntuació igual o inferior a `face_liveness_score_decline_threshold` (per defecte `30`), - `LIVENESS_FACE_ATTACK`: el model ha detectat un atac de presentació, - `FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST`: la cara coincideix amb una entrada de la teva llista de bloqueig facial. `MULTIPLE_FACES_DETECTED` és un senyal de gravetat `warning` (no rebutja), i `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` són senyals de gravetat `information` que indiquen que la mateixa cara ja ha aparegut en una altra sessió aprovada (mai no rebutgen). `face_quality` i `face_luminance` (0–100, que pot ser nul) descriuen la qualitat de la captura. **Cribratge de llista de bloqueig i duplicats.** S'executa a **cada** crida (amb o sense `save_api_request`) comparant la cara detectada amb l'índex de cerca facial de la teva aplicació. Les cares prèvies amb el mateix `vendor_data` s'exclouen de tota la cerca a l'índex; per tant, tornar a executar la prova de vida per al mateix usuari no activa `DUPLICATED_FACE`, i una cara a la llista de bloqueig originada en una sessió amb el mateix `vendor_data` de qui fa la crida tampoc NO es marca (el cribratge `FACE_IN_BLOCKLIST` s'omet per a cares amb el mateix `vendor_data`). **Facturació.** Cada resposta `200` consumeix un crèdit de l'API de Passive Liveness (pagat des del crèdit del teu pla o del saldo de recàrrega). Un saldo insuficient retorna `403` abans de qualsevol processament de la imatge. **Persistència de sessions i registre facial (`save_api_request`, per defecte `true`).** Quan és `true`, la crida es persisteix com una sessió de tipus API (Business Console, `GET /v3/session/{sessionId}/decision/` mitjançant el `request_id` retornat, webhook `status.updated`), la imatge de referència i el retall de la cara s'emmagatzemen, i la cara detectada **es registra al teu índex de cerca facial** perquè les crides posteriors de Cerca facial i les comprovacions de duplicats hi puguin coincidir. Quan és `false`, la crida és d'un sol ús: no s'emmagatzema res i la cara no es registra (el cribratge de llista de bloqueig i duplicats se segueix executant). **Sandbox.** Les claus d'API de sandbox ometen tot el processament i la facturació: després de la validació de la sol·licitud (l'entrada mal formada continua retornant `400`), l'endpoint retorna un payload simulat estàtic `Approved`, no es persisteix 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.** Pressupost d'escriptura compartit de 300 sol·licituds/min per clau d'API entre tots els endpoints POST/PATCH/DELETE; superar-lo retorna `429`. operationId: post_v3passive-liveness parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image properties: user_image: type: string format: binary description: >- Imatge frontal del rostre (p. ex., una selfie). Extensions permeses: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Mida màxima de càrrega: **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, de manera que una resolució gaire alta no millora la precisió. La imatge ha de contenir un sol subjecte; si hi ha diverses cares presents, s'avalua la més gran i s'afegeix una advertència `MULTIPLE_FACES_DETECTED`. face_liveness_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Llindar de puntuació de prova de vida (0–100). Una puntuació calculada **igual o inferior** a aquest valor emet una advertència `LOW_LIVENESS_SCORE` i estableix `status` com a `Declined`. Per defecte és `30`; augmenta'l per a una postura antisuplantació més estricta. Els valors fora de 0–100 retornen `400`. example: 30 rotate_image: type: boolean default: false description: >- Quan és `true`, el servei prova rotacions de 90 graus de l'entrada i utilitza l'orientació que ofereix la millor detecció facial. Útil quan falta l'orientació EXIF. Afegeix latència. example: false save_api_request: type: boolean default: true description: >- Quan és `true` (per defecte), manté la crida com una sessió de tipus API, emmagatzema les imatges de la cara, emet un webhook `status.updated` i inscriu la cara detectada al teu índex de cerca facial. Quan és `false`, la crida és d'un sol ús: no s'emmagatzema res i la cara no s'inscriu. El cribratge de llistes de bloqueig i duplicats s'executa en ambdós casos. example: true vendor_data: type: string description: >- Identificador opac opcional (el teu ID d'usuari, correu electrònic, UUID…) desat a la sessió persistent i retornat a la resposta. També s'utilitza per excloure sessions anteriors amb el mateix `vendor_data` de la comprovació de cares duplicades, de manera que reverificar el mateix usuari no genera `DUPLICATED_FACE`. example: user-123 metadata: type: object additionalProperties: true description: >- Objecte JSON opcional emmagatzemat amb la sessió (quan `save_api_request=true`) i retornat. En sol·licituds multipart, envia'l com a camp de cadena codificat en JSON; s'analitza com un objecte. example: flow: withdrawal example: user_image: (binary JPEG/PNG selfie) face_liveness_score_decline_threshold: 30 rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: withdrawal responses: '200': description: >- Prova de vida passiva completada. `liveness.score` és la confiança del model de 0 a 100 que la imatge mostra una persona viva; `status` és `Approved` tret que s'hagi activat una advertència de gravetat `error`. Una cara suplantada o a la llista de bloqueig continua retornant `200` — inspecciona `liveness.status` i `liveness.warnings`, no només el codi HTTP. Quan `save_api_request=true`, `request_id` és l'id de la sessió persistida. content: application/json: examples: Approved: summary: Cara viva — sense advertències value: request_id: a1b2c3d4-e5f6-7890-1234-567890abcdef liveness: status: Approved method: PASSIVE score: 95 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 warnings: [] face_quality: 84.21 face_luminance: 50.33 vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' Declined - presentation attack: summary: >- El model ha detectat una suplantació (impressió, reproducció, màscara…) value: request_id: f1c8c9b2-d3e4-4f5a-9b8c-7d6e5f4a3b2c liveness: status: Declined method: PASSIVE score: 12.5 user_image: entities: - bbox: - 100 - 120 - 420 - 540 confidence: 0.81 age: 30.1 gender: female race: null best_angle: 0 warnings: - risk: LOW_LIVENESS_SCORE feature: LIVENESS additional_data: null log_type: error short_description: Low liveness score long_description: >- The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data. - risk: LIVENESS_FACE_ATTACK feature: LIVENESS additional_data: null log_type: error short_description: Liveness Face Attack long_description: >- The system detected a potential attempt to bypass the liveness check. face_quality: 72.4 face_luminance: 48.2 vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' Declined - face on blocklist: summary: >- Cara viva, però coincideix amb una entrada de la llista de bloqueig value: request_id: 0b54a1de-22aa-4e0f-9c84-5a2b1f3c4d5e liveness: status: Declined method: PASSIVE score: 93.75 user_image: entities: - bbox: - 40 - 40 - 100 - 100 confidence: 0.722082 age: 27 gender: male race: null best_angle: 0 warnings: - risk: FACE_IN_BLOCKLIST feature: LIVENESS additional_data: blocklisted_session_id: 882c42d5-8a4d-4d20-8080-a22f57822c86 blocklisted_session_number: 3242 api_service: null log_type: error short_description: Face in blocklist long_description: >- The system identified a face in the blocklist, which means the face is not allowed to be verified. face_quality: null face_luminance: null vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+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. liveness: type: object properties: status: type: string enum: - Approved - Declined description: >- `Declined` quan s'ha activat almenys una advertència de gravetat `error` (cap cara, puntuació baixa, atac de presentació o coincidència amb la llista de bloqueig); `Approved` en cas contrari. Les entrades `warning`/`information` (múltiples cares, duplicats) mai no rebutgen per si soles. method: type: string enum: - PASSIVE description: Sempre `PASSIVE` per a aquest endpoint. score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Confiança de la prova de vida (0–100, dos decimals) que la imatge mostra una persona real i no pas una suplantació. `null` quan el model no ha retornat cap confiança. example: 95 user_image: type: object description: >- Resultats de la detecció facial per a la imatge enviada. 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 prova de vida. 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. La cara més gran és la que s'avalua. best_angle: type: integer nullable: true description: >- Rotació (graus) que ha produït la millor detecció facial; diferent de zero només quan `rotate_image=true` ha corregit l'orientació. example: 0 warnings: type: array description: >- Senyals de risc. Gravetat `error` (rebutja): `NO_FACE_DETECTED`, `LOW_LIVENESS_SCORE` (puntuació igual o inferior al llindar), `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, `POSSIBLE_FACE_IN_BLOCKLIST`. Gravetat `warning` (revisió, no comporta un rebuig): `MULTIPLE_FACES_DETECTED`. Gravetat `information` (no comporta un rebuig): `DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE` — la mateixa cara ja ha aparegut en una altra sessió aprovada. items: type: object properties: risk: type: string enum: - NO_FACE_DETECTED - LOW_LIVENESS_SCORE - LIVENESS_FACE_ATTACK - MULTIPLE_FACES_DETECTED - FACE_IN_BLOCKLIST - POSSIBLE_FACE_IN_BLOCKLIST - DUPLICATED_FACE - POSSIBLE_DUPLICATED_FACE description: Codi de risc llegible per màquina. feature: type: string enum: - LIVENESS description: >- Funcionalitat que ha generat l'advertència. Sempre `LIVENESS` en aquest endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- `null` per a la majoria d'advertències. Les coincidències amb la llista de bloqueig inclouen `{blocklisted_session_id, blocklisted_session_number, api_service}`; les coincidències per duplicat inclouen `{duplicated_session_id, duplicated_session_number, api_service}`, que apunten a la sessió coincident. 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. face_quality: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Puntuació de qualitat de captura de la cara detectada, normalitzada de 0 a 100. `null` quan el model no ha pogut produir un valor fiable. example: 84.21 face_luminance: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Brillantor de la cara detectada, normalitzada de 0 a 100. `null` quan no estigui disponible. example: 50.33 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 `user_image`, supera els 5 MB, té una extensió no admesa, falla la descodificació de la imatge al servidor o quan una opció està fora de rang. Els errors de camp utilitzen l'embolcall `{field: [messages]}` de DRF; els errors de descodificació d'imatge utilitzen `{"error": ...}`. content: application/json: examples: Missing image: summary: '`user_image` no s''ha inclòs a les dades del formulari' value: user_image: - No file was submitted. Invalid image format: summary: >- Extensió permesa però contingut de la imatge indescodificable value: error: Invalid user image format. code: invalid_image 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 '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/passive-liveness/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'face_liveness_score_decline_threshold=30' \ -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.passive_liveness.check( user_image=open("user_image.jpg", "rb"), face_liveness_score_decline_threshold=30.0, rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "withdrawal"}, ) 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.passiveLiveness.check({ user_image: await fileFromPath("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "withdrawal" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.PassiveLiveness.Check(ctx, didit.PassiveLivenessCheckParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tFaceLivenessScoreDeclineThreshold: didit.Float(30.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\": \"withdrawal\"}),\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.PassiveLivenessCheckParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.passiveLiveness().check(PassiveLivenessCheckParams.builder() .userImage(Path.of("user_image.jpg")) .faceLivenessScoreDeclineThreshold(30.0) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "withdrawal")) .build()); System.out.println(result); - lang: php label: PHP source: |- passiveLiveness->check([ 'user_image' => File::fromPath('user_image.jpg'), 'face_liveness_score_decline_threshold' => 30.0, 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'withdrawal'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.passive_liveness.check( user_image: Pathname("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "withdrawal" } ) 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.PassiveLiveness.CheckAsync(new PassiveLivenessCheckParams { UserImage = FileUpload.FromPath("user_image.jpg"), FaceLivenessScoreDeclineThreshold = 30.0, RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "withdrawal" }, }); 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.