> ## 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. # Détection du vivant passive : API et deepfakes > Didit détecte masques, impressions, rejeux et deepfakes à partir d'une seule image. Inférence sous 2s, paiement à l'usage, sans minimum. ## OpenAPI ````yaml fr/openapi-25.json POST /v3/passive-liveness/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de vérification d'identité. Authentifiez-vous avec l'en-tête x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/passive-liveness/: post: tags: - Standalone APIs summary: Détection passive du vivant description: >- Détectez les attaques par présentation — photos imprimées, relectures sur écran, masques, deepfakes — à partir d'une seule image de visage. Aucune vidéo, aucun mouvement ni aucune interaction de l'utilisateur n'est requis. **Fonctionnement.** L'image est analysée par un modèle biométrique ; le visage détecté le plus grand est évalué et un `score` de vivacité (0–100) est calculé. Le `status` est `Declined` lorsqu'un avertissement de gravité `error` se déclenche : - `NO_FACE_DETECTED` — le modèle de vivacité n'a trouvé aucun visage, - `LOW_LIVENESS_SCORE` — score inférieur ou égal à `face_liveness_score_decline_threshold` (`30` par défaut), - `LIVENESS_FACE_ATTACK` — le modèle a détecté une attaque par présentation, - `FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST` — le visage correspond à une entrée de votre liste de blocage de visages. `MULTIPLE_FACES_DETECTED` est un signal de gravité `warning` (ne refuse pas), et `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` sont des signaux de gravité `information` indiquant que le même visage est déjà apparu dans une autre session approuvée (ils ne refusent jamais). `face_quality` et `face_luminance` (0–100, nullable) décrivent la qualité de capture. **Filtrage des doublons et de la liste de blocage.** S'exécute à **chaque** appel — avec ou sans `save_api_request` — en comparant le visage détecté à l'index de recherche faciale de votre application. Les visages antérieurs ayant le même `vendor_data` sont exclus de l'ensemble de la recherche d'index — ainsi, réexécuter la détection du vivant pour le même utilisateur ne déclenche pas `DUPLICATED_FACE`, et un visage placé sur liste de blocage provenant d'une session avec le propre `vendor_data` de l'appelant n'est PAS non plus signalé (le filtrage `FACE_IN_BLOCKLIST` est ignoré pour les visages ayant le même `vendor_data`). **Facturation.** Chaque réponse `200` consomme un crédit d'API Passive Liveness (déduit du crédit de votre forfait ou de votre solde de recharge). Un solde insuffisant renvoie `403` avant tout traitement d'image. **Persistance de session et enregistrement de visage (`save_api_request`, `true` par défaut).** Lorsqu'il est défini sur `true`, l'appel est conservé sous forme de session de type API (Business Console, `GET /v3/session/{sessionId}/decision/` via le `request_id` renvoyé, webhook `status.updated`), l'image de référence et le recadrage du visage sont stockés, et le visage détecté est **enregistré dans votre index de recherche faciale** afin que les futurs appels à la Recherche faciale et les vérifications de doublons puissent y correspondre. Lorsqu'il est défini sur `false`, l'appel est ponctuel : rien n'est stocké et le visage n'est pas enregistré (le filtrage de la liste de blocage et des doublons s'exécute toujours). **Sandbox.** Les clés API de sandbox ignorent tout traitement et facturation : après validation de la requête (une entrée mal formée renvoie toujours `400`), l'endpoint renvoie un payload fictif statique `Approved`, aucune session n'est conservée et aucun crédit n'est consommé. **Authentification.** Envoyez la clé API de votre application dans l'en-tête `x-api-key`. Des identifiants manquants ou non valides renvoient `403` (`{"detail": "You do not have permission to perform this action."}`) — cette API ne renvoie jamais `401`. **Limite de débit.** Budget d'écriture partagé de 300 requêtes/min par clé API sur l'ensemble des endpoints POST/PATCH/DELETE ; tout dépassement renvoie `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: >- Image du visage de face (par exemple un selfie). Extensions autorisées : `tiff`, `jpg`, `jpeg`, `png`, `webp`. Taille maximale de téléversement : **5 MB** (les fichiers plus volumineux sont rejetés avec une erreur `400`). Les images sont automatiquement compressées à ~0.5 MB avant traitement, de sorte que les très hautes résolutions n'améliorent pas la précision. L'image doit contenir un seul sujet — lorsque plusieurs visages sont présents, le plus grand est évalué et un avertissement `MULTIPLE_FACES_DETECTED` est ajouté. face_liveness_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Seuil du score de détection du vivant (0–100). Un score calculé **inférieur ou égal** à cette valeur émet un avertissement `LOW_LIVENESS_SCORE` et définit `status` sur `Declined`. Valeur par défaut `30` ; augmentez-la pour une posture anti-usurpation plus stricte. Les valeurs en dehors de 0–100 renvoient `400`. example: 30 rotate_image: type: boolean default: false description: >- Lorsque la valeur est `true`, le service applique des rotations de 90 degrés à l'image fournie et utilise l'orientation qui produit la meilleure détection faciale. Utile lorsque l'orientation EXIF est manquante. Ajoute de la latence. example: false save_api_request: type: boolean default: true description: >- Lorsque la valeur est `true` (par défaut), conserve l'appel sous forme de session de type API, stocke les images de visage, émet un webhook `status.updated` et enregistre le visage détecté dans votre index de recherche faciale. Lorsque la valeur est `false`, l'appel est ponctuel — rien n'est stocké et le visage n'est pas enregistré. Le filtrage par liste de blocage et la détection des doublons s'exécutent dans les deux cas. example: true vendor_data: type: string description: >- Identifiant opaque optionnel (votre identifiant d'utilisateur, e-mail, UUID…) stocké sur la session persistée et renvoyé. Également utilisé pour exclure les sessions antérieures avec le même `vendor_data` de la vérification de visage en double, afin que la revérification du même utilisateur ne déclenche pas `DUPLICATED_FACE`. example: user-123 metadata: type: object additionalProperties: true description: >- Objet JSON optionnel stocké avec la session (lorsque `save_api_request=true`) et renvoyé. Dans les requêtes multipart, envoyez-le sous forme de champ textuel encodé en JSON — il est analysé sous forme d'objet. 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: "Détection passive du vivant terminée. `liveness.score` est la confiance de 0 à 100 du modèle indiquant que l'image montre une personne vivante\_; `status` est `Approved` sauf si un avertissement de gravité `error` a été déclenché. Un visage usurpé ou sur liste de blocage renvoie tout de même `200`\_— examinez `liveness.status` et `liveness.warnings`, et pas seulement le code HTTP. Lorsque `save_api_request=true`, `request_id` est l'identifiant de session conservé." content: application/json: examples: Approved: summary: Visage vivant — aucun avertissement 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: >- Le modèle a signalé une usurpation (impression, rejeu, masque…) 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: >- Visage vivant, mais il correspond à une entrée de liste de blocage 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: "Identifiant de session persistante lorsque `save_api_request=true` (utilisable avec `GET /v3/session/{sessionId}/decision/`)\_; sinon un UUID de corrélation temporaire." liveness: type: object properties: status: type: string enum: - Approved - Declined description: >- `Declined` lorsqu'au moins un avertissement de gravité `error` s'est déclenché (aucun visage, score faible, attaque par présentation ou correspondance dans une liste de blocage) ; `Approved` dans les autres cas. Les entrées `warning`/`information` (visages multiples, doublons) n'entraînent jamais de refus à elles seules. method: type: string enum: - PASSIVE description: Toujours `PASSIVE` pour cet endpoint. score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Confiance de détection du vivant (0–100, deux décimales) indiquant que l'image représente une personne vivante plutôt qu'une usurpation. `null` lorsque le modèle n'a renvoyé aucune confiance. example: 95 user_image: type: object description: >- Résultats de la détection faciale pour l'image soumise. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Boîte englobante du visage détecté sous forme de coordonnées en pixels `[x_min, y_min, x_max, y_max]` dans l'image traitée. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: >- Indice de confiance de la détection faciale (0–1). example: 0.732973 age: type: number format: float description: >- Âge estimé par le modèle pour le visage détecté, en années. À titre informatif uniquement — n'affecte pas la décision de détection du vivant. example: 26.91 gender: type: string description: >- Genre prédit par le modèle pour le visage détecté (`male` ou `female`). À titre informatif uniquement. example: male race: type: string nullable: true description: >- Champ réservé — toujours `null` dans les réponses de cet endpoint. example: null description: >- Une entrée par visage détecté. Le visage le plus grand est celui qui est évalué. best_angle: type: integer nullable: true description: >- Rotation (en degrés) ayant produit la meilleure détection de visage ; non nulle uniquement lorsque `rotate_image=true` a corrigé l'orientation. example: 0 warnings: type: array description: >- Signaux de risque. Gravité `error` (refus) : `NO_FACE_DETECTED`, `LOW_LIVENESS_SCORE` (score inférieur ou égal au seuil), `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, `POSSIBLE_FACE_IN_BLOCKLIST`. Gravité `warning` (examen, pas de refus) : `MULTIPLE_FACES_DETECTED`. Gravité `information` (pas de refus) : `DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE` — le même visage est déjà apparu dans une autre session approuvée. 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: Code de risque lisible par machine. feature: type: string enum: - LIVENESS description: >- Fonctionnalité ayant émis l'avertissement. Toujours `LIVENESS` sur cet endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- `null` pour la plupart des avertissements. Les correspondances avec la liste de blocage contiennent `{blocklisted_session_id, blocklisted_session_number, api_service}` ; les correspondances de doublons contiennent `{duplicated_session_id, duplicated_session_number, api_service}` qui pointent vers la session correspondante. log_type: type: string enum: - error - warning - information description: >- Gravité. Les avertissements `error` font passer `status` à `Declined` ; les entrées `warning` et `information` sont indicatives et ne refusent jamais d'elles-mêmes. short_description: type: string description: >- Résumé du risque en une ligne, lisible par l'utilisateur. long_description: type: string description: Explication lisible par l'humain du risque. face_quality: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Score de qualité de capture du visage détecté, normalisé de 0 à 100. `null` lorsque le modèle n'a pas pu produire une valeur fiable. example: 84.21 face_luminance: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Luminosité du visage détecté, normalisée de 0 à 100. `null` lorsqu'elle n'est pas disponible. example: 50.33 vendor_data: type: string nullable: true description: Écho des `vendor_data` que vous avez envoyées, ou `null`. metadata: type: object nullable: true additionalProperties: true description: >- Écho de l'objet `metadata` que vous avez envoyé, ou `null`. created_at: type: string format: date-time description: >- Horodatage ISO 8601 (UTC) du moment où la réponse a été générée, ex. `2026-06-12T01:04:42.763237+00:00`. '400': description: >- Erreur de validation. Renvoyée lorsque `user_image` est manquant, dépasse 5 Mo, possède une extension non prise en charge, échoue au décodage de l'image côté serveur, ou lorsqu'une option est hors limites. Les erreurs de champ utilisent l'enveloppe `{field: [messages]}` de DRF ; les échecs de décodage d'image utilisent `{"error": ...}`. content: application/json: examples: Missing image: summary: '`user_image` non inclus dans les données de formulaire' value: user_image: - No file was submitted. Invalid image format: summary: Extension autorisée mais contenu d'image indécodable value: error: Invalid user image format. code: invalid_image Unsupported file extension: summary: Extension de fichier autre que 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: Le téléversement dépasse la limite de 5 MB value: user_image: - File size should not exceed 5 MB '403': description: "Permission refusée. Renvoyé lorsque l'en-tête `x-api-key` est manquant, ainsi que lorsque le solde de l'organisation appelante ne permet pas de couvrir l'appel\_; une clé incorrecte, révoquée ou expirée renvoie `401`. Une clé manquante renvoie `403` avec `{\"detail\": ...}`\_; une clé incorrecte, révoquée ou expirée renvoie `401`. Les crédits insuffisants renvoient `403` avec `{\"error\": ...}` avant tout traitement d'image." content: application/json: examples: Missing or invalid API key: summary: Aucun en-tête `x-api-key`, ou la clé est non valide/révoquée value: detail: You do not have permission to perform this action. Not enough credits: summary: Le solde de l'organisation ne peut pas couvrir l'appel value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Limite de débit dépassée. Les endpoints POST/PATCH/DELETE partagent un budget de 300 requêtes d'écriture par minute par clé API (la création de transactions et l'ingestion d'événements ont un budget distinct de 600). La réponse comporte les en-têtes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` et `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: >- Plus de 300 requêtes d'écriture au cours de la minute actuelle 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 clé API de votre application, issue de Développeurs -> Clés API dans la Business Console. La clé principale dispose d'un accès complet. Une clé nommée peut être restreinte : aucun, lecture ou écriture par ressource, limitée à certains workflows ou aux sessions approuvées, à une liste d'adresses IP et à une date d'expiration. 401 signifie que la clé est incorrecte, révoquée ou expirée ; 403 signifie qu'aucune clé n'a été envoyée, que la clé n'a pas accès à cette ressource ou action, ou que la requête provient d'une adresse hors de sa liste d'IP ; 404 sur une route de session signifie que la session est hors des workflows ou des statuts de la clé. Une clé sans accès aux médias reçoit les URL d'images, de vidéos et de PDF à null, et une clé sans accès en écriture aux sessions reçoit les liens et tokens de session à null. Voir https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.