> ## 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. # Rilevamento della vitalità passivo: API e deepfake > Con Didit rileva maschere, stampe, replay e deepfake da una sola immagine. Passivo, sotto 2s, prezzi a consumo, nessun minimo. ## OpenAPI ````yaml it/openapi-25.json POST /v3/passive-liveness/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API di verifica dell'identità. Autenticati con l'intestazione x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/passive-liveness/: post: tags: - Standalone APIs summary: Rilevamento passivo della vitalità description: >- Rileva gli attacchi di presentazione — foto stampate, riproduzioni su schermo, maschere, deepfake — da una singola immagine del volto. Non richiede video, movimento o interazione con l'utente. **Come funziona.** L'immagine viene analizzata da un modello biometrico; il volto rilevato più grande viene valutato e viene calcolato uno `score` di vitalità (0–100). Lo `status` è `Declined` quando viene attivato un avviso con gravità `error`: - `NO_FACE_DETECTED` — il modello di vitalità non ha rilevato alcun volto, - `LOW_LIVENESS_SCORE` — punteggio pari o inferiore a `face_liveness_score_decline_threshold` (valore predefinito `30`), - `LIVENESS_FACE_ATTACK` — il modello ha rilevato un attacco di presentazione, - `FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST` — il volto corrisponde a una voce presente nella tua blocklist dei volti. `MULTIPLE_FACES_DETECTED` è un segnale con gravità `warning` (non comporta il rifiuto), mentre `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` sono segnali con gravità `information` che indicano che lo stesso volto è già comparso in un'altra sessione approvata (non comportano mai il rifiuto). `face_quality` e `face_luminance` (0–100, nullable) descrivono la qualità di acquisizione. **Screening per blocklist e duplicati.** Viene eseguito a **ogni** chiamata — con o senza `save_api_request` — confrontando il volto rilevato con l'indice di Ricerca facciale della tua applicazione. I volti precedenti con lo stesso `vendor_data` vengono esclusi dall'intera ricerca nell'indice — quindi eseguire nuovamente il rilevamento della vitalità per lo stesso utente non attiva `DUPLICATED_FACE`, e anche un volto in blocklist originato da una sessione con lo stesso `vendor_data` del chiamante NON viene segnalato (lo screening `FACE_IN_BLOCKLIST` viene ignorato per i volti con lo stesso `vendor_data`). **Fatturazione.** Ogni risposta `200` consuma un credito dell'API Passive Liveness (addebitato dal credito del tuo piano o dal saldo di ricarica). Un saldo insufficiente restituisce `403` prima di qualsiasi elaborazione dell'immagine. **Persistenza della sessione e registrazione del volto (`save_api_request`, predefinito `true`).** Quando è `true`, la chiamata viene salvata come sessione di tipo API (Business Console, `GET /v3/session/{sessionId}/decision/` tramite il `request_id` restituito, webhook `status.updated`), l'immagine di riferimento e il ritaglio del volto vengono memorizzati e il volto rilevato viene **registrato nell'indice di Ricerca facciale** affinché le successive chiamate a Ricerca facciale e i controlli dei duplicati possano trovarlo. Quando è `false`, la chiamata è una tantum: non viene memorizzato nulla e il volto non viene registrato (lo screening per blocklist/duplicati viene comunque eseguito). **Sandbox.** Le chiavi API di sandbox ignorano tutte le elaborazioni e la fatturazione: dopo la validazione della richiesta (i dati di input non validi restituiscono comunque `400`), l'endpoint restituisce un payload fittizio statico `Approved`, non viene salvata alcuna sessione e non vengono consumati crediti. **Autenticazione.** Invia la chiave API della tua applicazione nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403` (`{"detail": "You do not have permission to perform this action."}`) — questa API non restituisce mai `401`. **Limite di frequenza.** Budget di scrittura condiviso di 300 richieste/min per chiave API su tutti gli endpoint POST/PATCH/DELETE; il superamento restituisce `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: >- Immagine frontale del viso (ad es. un selfie). Estensioni consentite: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Dimensione massima di caricamento: **5 MB** (i file più grandi vengono rifiutati con `400`). Le immagini vengono compresse automaticamente a ~0.5 MB prima dell'elaborazione, pertanto risoluzioni molto elevate non migliorano la precisione. L'immagine deve contenere un unico soggetto — quando sono presenti più volti, viene valutato quello più grande e viene aggiunto un avviso `MULTIPLE_FACES_DETECTED`. face_liveness_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Soglia del punteggio di rilevamento della vitalità (0–100). Un punteggio calcolato **pari o inferiore** a questo valore genera un avviso `LOW_LIVENESS_SCORE` e imposta `status` su `Declined`. Predefinito `30`; aumentala per un livello anti-spoofing più restrittivo. I valori non compresi tra 0 e 100 restituiscono `400`. example: 30 rotate_image: type: boolean default: false description: >- Quando è `true`, il servizio prova rotazioni di 90 gradi dell'input e utilizza l'orientamento che offre il miglior rilevamento del volto. Utile quando manca l'orientamento EXIF. Aggiunge latenza. example: false save_api_request: type: boolean default: true description: >- Quando è `true` (predefinito), memorizza la chiamata come sessione di tipo API, salva le immagini del volto, emette un webhook `status.updated` e registra il volto rilevato nel tuo indice di Ricerca facciale. Quando è `false`, la chiamata è una tantum: non viene memorizzato nulla e il volto non viene registrato. Lo screening della blocklist e dei duplicati viene eseguito in entrambi i casi. example: true vendor_data: type: string description: >- Identificativo opaco opzionale (il tuo ID utente, email, UUID...) memorizzato nella sessione persistita e restituito. Viene utilizzato anche per escludere le sessioni precedenti con lo stesso `vendor_data` dal controllo dei volti duplicati, in modo che la nuova verifica dello stesso utente non generi `DUPLICATED_FACE`. example: user-123 metadata: type: object additionalProperties: true description: >- Oggetto JSON opzionale memorizzato con la sessione (quando `save_api_request=true`) e restituito nella risposta. Nelle richieste multipart, invialo come campo stringa con codifica JSON: viene interpretato come oggetto. 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: >- Rilevamento passivo della vitalità completato. `liveness.score` è il livello di affidabilità da 0 a 100 del modello che l'immagine mostri una persona viva; `status` è `Approved` a meno che non sia scattato un avviso con gravità `error`. Un volto falsificato o inserito in blocklist restituisce comunque `200` — esamina `liveness.status` e `liveness.warnings`, non solo il codice HTTP. Quando `save_api_request=true`, `request_id` è l'ID di sessione salvato. content: application/json: examples: Approved: summary: Volto dal vivo — nessun avviso 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: >- Il modello ha segnalato uno spoofing (stampa, replay, maschera…) 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: Volto dal vivo, ma corrisponde a una voce della blocklist 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 della sessione salvata quando `save_api_request=true` (utilizzabile con `GET /v3/session/{sessionId}/decision/`); altrimenti un UUID di correlazione temporaneo. liveness: type: object properties: status: type: string enum: - Approved - Declined description: >- `Declined` quando è scattato almeno un avviso con gravità `error` (nessun volto, punteggio basso, attacco di presentazione o riscontro nella blocklist); `Approved` altrimenti. Le voci `warning`/`information` (volti multipli, duplicati) non determinano mai il rifiuto da sole. method: type: string enum: - PASSIVE description: Sempre `PASSIVE` per questo endpoint. score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Affidabilità del rilevamento della vitalità (0–100, due decimali) che l'immagine ritragga una persona reale anziché uno spoofing. `null` se il modello non ha restituito alcuna affidabilità. example: 95 user_image: type: object description: >- Risultati del rilevamento facciale per l'immagine inviata. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Riquadro di delimitazione del volto rilevato come coordinate in pixel `[x_min, y_min, x_max, y_max]` nell'immagine elaborata. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: Affidabilità del rilevamento facciale (0–1). example: 0.732973 age: type: number format: float description: >- Età stimata dal modello per il volto rilevato, in anni. Solo a scopo informativo: non influisce sulla decisione del rilevamento della vitalità. example: 26.91 gender: type: string description: >- Genere previsto dal modello per il volto rilevato (`male` o `female`). Solo a scopo informativo. example: male race: type: string nullable: true description: >- Campo riservato — sempre `null` nelle risposte di questo endpoint. example: null description: >- Una voce per ogni volto rilevato. Il volto più grande è quello valutato. best_angle: type: integer nullable: true description: >- Rotazione (gradi) che ha prodotto il miglior rilevamento del volto; diversa da zero solo quando `rotate_image=true` ha corretto l'orientamento. example: 0 warnings: type: array description: >- Segnali di rischio. Gravità `error` (comporta il rifiuto): `NO_FACE_DETECTED`, `LOW_LIVENESS_SCORE` (punteggio pari o inferiore alla soglia), `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, `POSSIBLE_FACE_IN_BLOCKLIST`. Gravità `warning` (revisione, nessun rifiuto): `MULTIPLE_FACES_DETECTED`. Gravità `information` (nessun rifiuto): `DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE` — lo stesso volto è già apparso in un'altra sessione approvata. 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: Codice di rischio leggibile dalla macchina. feature: type: string enum: - LIVENESS description: >- Funzionalità che ha generato l'avviso. Sempre `LIVENESS` su questo endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- `null` per la maggior parte degli avvisi. Le corrispondenze con la blocklist riportano `{blocklisted_session_id, blocklisted_session_number, api_service}`; i duplicati rilevati riportano `{duplicated_session_id, duplicated_session_number, api_service}` che puntano alla sessione corrispondente. log_type: type: string enum: - error - warning - information description: >- Gravità. Gli avvisi `error` portano `status` a `Declined`; le voci `warning` e `information` sono informative e non determinano mai un rifiuto da sole. short_description: type: string description: >- Riepilogo del rischio su una riga leggibile dall'utente. long_description: type: string description: Spiegazione di facile lettura del rischio. face_quality: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Punteggio di qualità di acquisizione del volto rilevato, normalizzato tra 0 e 100. `null` quando il modello non è riuscito a produrre un valore affidabile. example: 84.21 face_luminance: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Luminosità del volto rilevato, normalizzata tra 0 e 100. `null` se non disponibile. example: 50.33 vendor_data: type: string nullable: true description: Eco del `vendor_data` inviato, o `null`. metadata: type: object nullable: true additionalProperties: true description: Eco dell'oggetto `metadata` inviato, o `null`. created_at: type: string format: date-time description: >- Timestamp ISO 8601 (UTC) di generazione della risposta, ad es. `2026-06-12T01:04:42.763237+00:00`. '400': description: >- Errore di validazione. Restituito quando `user_image` è mancante, supera 5 MB, ha un'estensione non supportata, non supera la decodifica dell'immagine lato server o quando un'opzione è fuori intervallo. Gli errori di campo utilizzano l'envelope `{field: [messages]}` di DRF; gli errori di decodifica dell'immagine utilizzano `{"error": ...}`. content: application/json: examples: Missing image: summary: '`user_image` non incluso nei dati del modulo' value: user_image: - No file was submitted. Invalid image format: summary: >- Estensione consentita ma contenuto dell'immagine non decodificabile value: error: Invalid user image format. code: invalid_image Unsupported file extension: summary: Estensione del file diversa da 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: Il caricamento supera il limite di 5 MB value: user_image: - File size should not exceed 5 MB '403': description: >- Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante e anche quando il saldo dell'organizzazione chiamante non è sufficiente a coprire la chiamata; una chiave errata, revocata o scaduta restituisce `401`. Una chiave mancante restituisce `403` con `{"detail": ...}`; una chiave errata, revocata o scaduta restituisce `401`. Crediti insufficienti restituiscono `403` con `{"error": ...}` prima che avvenga qualsiasi elaborazione delle immagini. content: application/json: examples: Missing or invalid API key: summary: >- Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata value: detail: You do not have permission to perform this action. Not enough credits: summary: >- Il saldo dell'organizzazione non è sufficiente per coprire la chiamata value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Più di 300 richieste di scrittura nel minuto corrente 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 chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.