Vai al contenuto principale
POST
cURL

Autorizzazioni

x-api-key
string
header
obbligatorio

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.

Corpo

multipart/form-data
user_image
file
obbligatorio

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
number<float>
predefinito:30

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.

Intervallo richiesto: 0 <= x <= 100
Esempio:

30

rotate_image
boolean
predefinito:false

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.

Esempio:

false

save_api_request
boolean
predefinito:true

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.

Esempio:

true

vendor_data
string

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.

Esempio:

"user-123"

metadata
object

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.

Esempio:

Risposta

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.

request_id
string<uuid>

ID della sessione salvata quando save_api_request=true (utilizzabile con GET /v3/session/{sessionId}/decision/); altrimenti un UUID di correlazione temporaneo.

liveness
object
vendor_data
string | null

Eco del vendor_data inviato, o null.

metadata
object | null

Eco dell'oggetto metadata inviato, o null.

created_at
string<date-time>

Timestamp ISO 8601 (UTC) di generazione della risposta, ad es. 2026-06-12T01:04:42.763237+00:00.

Ultima modifica il 7 novembre 2026