Saltar al contenido principal
POST
cURL

Autorizaciones

x-api-key
string
header
requerido

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.

Cuerpo

multipart/form-data
user_image
file
requerido

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

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.

Rango requerido: 0 <= x <= 100
Ejemplo:

30

rotate_image
boolean
predeterminado:false

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.

Ejemplo:

false

save_api_request
boolean
predeterminado:true

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.

Ejemplo:

true

vendor_data
string

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.

Ejemplo:

"user-123"

metadata
object

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.

Ejemplo:

Respuesta

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.

request_id
string<uuid>

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
object
vendor_data
string | null

Devuelve el vendor_data que enviaste, o null.

metadata
object | null

Devuelve el objeto metadata que enviaste, o null.

created_at
string<date-time>

Marca de tiempo ISO 8601 (UTC) del momento en que se generó la respuesta, p. ej., 2026-06-12T01:04:42.763237+00:00.

Última modificación el 1 de noviembre de 2026