> ## 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 liveness pasivo: detección de deepfakes > Didit detecta máscaras, impresiones, reproducciones y deepfakes en una sola imagen. Pasivo, menos de 2 s, pago por uso y sin mínimos mensuales. ## OpenAPI ````yaml es/openapi-25.json POST /v3/passive-liveness/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificación de identidad. Autentícate con el encabezado x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/passive-liveness/: post: tags: - Standalone APIs summary: Prueba de vida pasiva description: >- Detecta ataques de presentación (fotos impresas, reproducciones en pantalla, máscaras, deepfakes) a partir de una sola imagen facial. No requiere vídeo, movimiento ni interacción del usuario. **Cómo funciona.** Un modelo biométrico analiza la imagen: evalúa el rostro más grande detectado y calcula una puntuación de prueba de vida (`score`, 0–100). `status` es `Declined` cuando se activa cualquier advertencia con severidad `error`: - `NO_FACE_DETECTED`: el modelo de prueba de vida no encontró ningún rostro, - `LOW_LIVENESS_SCORE`: puntuación igual o inferior a `face_liveness_score_decline_threshold` (por defecto `30`), - `LIVENESS_FACE_ATTACK`: el modelo detectó un ataque de presentación, - `FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST`: el rostro coincide con una entrada de tu lista de bloqueo de rostros. `MULTIPLE_FACES_DETECTED` es una señal de severidad `warning` (no rechaza), y `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` son señales de severidad `information` que indican que el mismo rostro ya apareció en otra sesión aprobada (nunca rechazan). `face_quality` y `face_luminance` (0–100, pueden ser null) describen la calidad de la captura. **Lista de bloqueo y detección de duplicados.** Se ejecuta en **cada** llamada, con o sin `save_api_request`, comparando el rostro detectado con el índice de búsqueda facial de tu aplicación. Los rostros previos con el mismo `vendor_data` se excluyen de toda la búsqueda en el índice. Por eso, volver a ejecutar la prueba de vida para el mismo usuario no activa `DUPLICATED_FACE`, y un rostro de la lista de bloqueo que provenga de una sesión con el mismo `vendor_data` del llamante tampoco se marca (la comprobación `FACE_IN_BLOCKLIST` se omite para los rostros con el mismo `vendor_data`). **Facturación.** Cada respuesta `200` consume un crédito de la API de prueba de vida pasiva (se paga con el crédito de tu plan o con tu saldo de recarga). Si el saldo es insuficiente, se devuelve `403` antes de procesar ninguna imagen. **Persistencia de la sesión e inscripción del rostro (`save_api_request`, por defecto `true`).** Cuando es `true`, la llamada se guarda como una sesión de tipo API (Business Console, `GET /v3/session/{sessionId}/decision/` mediante el `request_id` devuelto, webhook `status.updated`), se almacenan la imagen de referencia y el recorte del rostro, y el rostro detectado se **inscribe en tu índice de búsqueda facial** para que las llamadas posteriores a Búsqueda facial y las comprobaciones de duplicados puedan encontrarlo. Cuando es `false`, la llamada es puntual: no se almacena nada y el rostro no se inscribe (la comprobación de lista de bloqueo y de duplicados se sigue ejecutando). **Sandbox.** Con las claves de API de sandbox no hay procesamiento ni facturación: tras validar la solicitud (una entrada mal formada sigue devolviendo `400`), el endpoint devuelve un payload simulado estático `Approved`, no se guarda ninguna sesión y no se consumen créditos. **Autenticación.** Envía la clave de API de tu aplicación en el encabezado `x-api-key`. Si las credenciales faltan o no son válidas, se devuelve `403` (`{"detail": "You do not have permission to perform this action."}`): esta API nunca devuelve `401`. **Límite de solicitudes.** Hay un presupuesto de escritura compartido de 300 solicitudes/min por clave de API para todos los endpoints POST/PATCH/DELETE; si lo superas, se devuelve `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: >- Imagen frontal del rostro (p. ej., una selfie). Extensiones permitidas: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Tamaño máximo de carga: **5 MB** (los archivos más grandes se rechazan con `400`). Las imágenes se comprimen automáticamente a ~0.5 MB antes del procesamiento, por lo que las resoluciones muy altas no mejoran la precisión. La imagen debe contener una sola persona: cuando hay varios rostros, se evalúa el más grande y se añade una advertencia `MULTIPLE_FACES_DETECTED`. face_liveness_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Umbral de puntuación de la prueba de vida (0–100). Una puntuación calculada **igual o inferior** a este valor emite una advertencia `LOW_LIVENESS_SCORE` y establece `status` en `Declined`. El valor predeterminado es `30`; súbelo para una postura antisuplantación más estricta. Los valores fuera de 0–100 devuelven `400`. example: 30 rotate_image: type: boolean default: false description: >- Si es `true`, el servicio prueba rotaciones de 90 grados de la entrada y usa la orientación que ofrece la mejor detección facial. Útil cuando falta la orientación EXIF. Añade latencia. example: false save_api_request: type: boolean default: true description: >- Si es `true` (valor predeterminado), guarda la llamada como una sesión de tipo API, almacena las imágenes faciales, emite un webhook `status.updated` y registra el rostro detectado en tu índice de búsqueda facial. Si es `false`, la llamada es puntual: no se almacena nada y el rostro no se registra. Las comprobaciones de lista de bloqueo y de duplicados se ejecutan en ambos casos. example: true vendor_data: type: string description: >- Identificador opaco opcional (tu ID de usuario, correo electrónico, UUID…) que se guarda en la sesión persistida y se devuelve. También se usa para excluir de la comprobación de rostro duplicado las sesiones anteriores con el mismo `vendor_data`, de modo que reverificar al mismo usuario no genere `DUPLICATED_FACE`. example: user-123 metadata: type: object additionalProperties: true description: >- Objeto JSON opcional que se almacena con la sesión (cuando `save_api_request=true`) y se devuelve. En solicitudes multipart, envíalo como un campo de cadena codificado en JSON: se convierte en un objeto. 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: >- Prueba de vida pasiva completada. `liveness.score` es la confianza del modelo, de 0 a 100, de que la imagen muestra a una persona real; `status` es `Approved` salvo que se haya activado una advertencia de severidad `error`. Un rostro suplantado o incluido en la lista de bloqueo sigue devolviendo `200`: revisa `liveness.status` y `liveness.warnings`, no solo el código HTTP. Cuando `save_api_request=true`, `request_id` es el ID de la sesión guardada. content: application/json: examples: Approved: summary: Rostro real — sin advertencias 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 modelo detectó una suplantación (impresión, reproducción, 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: >- Rostro real, pero coincide con una entrada de la lista de bloqueo 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 la sesión guardada cuando `save_api_request=true` (se puede usar con `GET /v3/session/{sessionId}/decision/`); en caso contrario, un UUID de correlación temporal. liveness: type: object properties: status: type: string enum: - Approved - Declined description: >- `Declined` cuando se activó al menos una advertencia de gravedad `error` (ningún rostro, puntuación baja, ataque de presentación o coincidencia en la lista de bloqueo); `Approved` en caso contrario. Las entradas `warning`/`information` (varios rostros, duplicados) nunca provocan un rechazo por sí solas. method: type: string enum: - PASSIVE description: Siempre `PASSIVE` para este endpoint. score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Confianza de la prueba de vida (0–100, dos decimales) de que la imagen muestra a una persona real y no una suplantación. `null` cuando el modelo no devolvió ninguna confianza. example: 95 user_image: type: object description: >- Resultados de la detección facial de la imagen enviada. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Cuadro delimitador del rostro detectado, en coordenadas de píxeles `[x_min, y_min, x_max, y_max]` de la imagen procesada. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: Confianza de la detección facial (0–1). example: 0.732973 age: type: number format: float description: >- Edad del rostro detectado estimada por el modelo, en años. Solo es informativa: no afecta a la decisión de prueba de vida. example: 26.91 gender: type: string description: >- Género del rostro detectado predicho por el modelo (`male` o `female`). Solo es informativo. example: male race: type: string nullable: true description: >- Campo reservado: siempre es `null` en las respuestas de este endpoint. example: null description: >- Una entrada por rostro detectado. El rostro más grande es el que se evalúa. best_angle: type: integer nullable: true description: >- Rotación (en grados) que produjo la mejor detección facial; solo es distinta de cero cuando `rotate_image=true` corrigió la orientación. example: 0 warnings: type: array description: >- Señales de riesgo. Gravedad `error` (rechazan): `NO_FACE_DETECTED`, `LOW_LIVENESS_SCORE` (puntuación igual o inferior al umbral), `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, `POSSIBLE_FACE_IN_BLOCKLIST`. Gravedad `warning` (revisión, sin rechazo): `MULTIPLE_FACES_DETECTED`. Gravedad `information` (sin rechazo): `DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE`: el mismo rostro ya apareció en otra sesión aprobada. 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: Código de riesgo legible por máquina. feature: type: string enum: - LIVENESS description: >- Función que emitió la advertencia. En este endpoint siempre es `LIVENESS`. additional_data: type: object nullable: true additionalProperties: true description: >- `null` para la mayoría de las advertencias. Las coincidencias con la lista de bloqueo incluyen `{blocklisted_session_id, blocklisted_session_number, api_service}`; las coincidencias de duplicados incluyen `{duplicated_session_id, duplicated_session_number, api_service}`, que apuntan a la sesión coincidente. log_type: type: string enum: - error - warning - information description: >- Gravedad. Las advertencias `error` llevan `status` a `Declined`; las entradas `warning` e `information` son informativas y nunca rechazan por sí solas. short_description: type: string description: Resumen legible del riesgo en una línea. long_description: type: string description: Explicación legible del riesgo. face_quality: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Puntuación de la calidad de captura del rostro detectado, normalizada de 0 a 100. `null` cuando el modelo no pudo producir un valor fiable. example: 84.21 face_luminance: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Brillo del rostro detectado, normalizado de 0 a 100. `null` cuando no está disponible. example: 50.33 vendor_data: type: string nullable: true description: Devuelve el `vendor_data` que enviaste, o `null`. metadata: type: object nullable: true additionalProperties: true description: Devuelve el objeto `metadata` que enviaste, o `null`. created_at: type: string format: date-time description: >- Marca de tiempo ISO 8601 (UTC) del momento en que se generó la respuesta, p. ej., `2026-06-12T01:04:42.763237+00:00`. '400': description: >- Error de validación. Se devuelve cuando falta `user_image`, supera los 5 MB, tiene una extensión no admitida o no se puede decodificar la imagen en el servidor, o cuando una opción está fuera de rango. Los errores de campo usan el formato `{field: [messages]}` de DRF; los fallos de decodificación de imagen usan `{"error": ...}`. content: application/json: examples: Missing image: summary: '`user_image` no incluido en los datos del formulario' value: user_image: - No file was submitted. Invalid image format: summary: >- Extensión permitida, pero el contenido de la imagen no se puede decodificar value: error: Invalid user image format. code: invalid_image Unsupported file extension: summary: Extensión de archivo distinta de 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: El archivo supera el límite de 5 MB value: user_image: - File size should not exceed 5 MB '403': description: >- Permiso denegado. Se devuelve cuando falta el encabezado `x-api-key` y también cuando el saldo de la organización que realiza la llamada no la cubre; una clave incorrecta, revocada o expirada devuelve `401`. Si falta la clave, se devuelve `403` con `{"detail": ...}`; una clave incorrecta, revocada o expirada devuelve `401`. La falta de créditos devuelve `403` con `{"error": ...}` antes de que se procese ninguna imagen. content: application/json: examples: Missing or invalid API key: summary: >- Falta el encabezado `x-api-key`, o la clave no es válida o está revocada value: detail: You do not have permission to perform this action. Not enough credits: summary: El saldo de la organización no cubre la llamada value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Límite de solicitudes superado. Todos los endpoints POST/PATCH/DELETE comparten un presupuesto de 300 solicitudes de escritura por minuto por clave de API. La respuesta incluye los encabezados `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` y `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Más de 300 solicitudes de escritura en el minuto 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 clave de API de tu aplicación, que encontrarás en Developers -> API keys en la Business Console. La clave principal tiene acceso completo. Una clave con nombre puede tener un alcance limitado: ninguno, lectura o escritura por recurso, limitada a algunos flujos o a sesiones aprobadas, a una lista de direcciones IP y a una fecha de caducidad. 401 significa que la clave es incorrecta, se revocó o expiró; 403 significa que no se envió ninguna clave, que la clave no tiene acceso a este recurso o acción, o que la solicitud provino de una dirección fuera de su lista de IP; 404 en una ruta de sesión significa que la sesión está fuera de los flujos o estados de la clave. Una clave sin acceso a contenido multimedia recibe las URL de imágenes, videos y PDF como null, y una clave sin permiso de escritura en sesiones recibe los enlaces y tokens de sesión como null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.