> ## 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 estimación de edad: verificación con selfie > La API de Didit POST /v3/age-estimation/ estima la edad con IA desde un selfie con liveness pasiva. Sin documento, menos de 2 s y pago por uso. ## OpenAPI ````yaml es/openapi-25.json POST /v3/age-estimation/ 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/age-estimation/: post: tags: - Standalone APIs summary: Estimación de edad (edad facial + prueba de vida pasiva) description: >- Estima la edad de una persona a partir de una sola foto del rostro y ejecuta una prueba de vida pasiva en la misma llamada: devuelve la `age_estimation` predicha por el modelo (en años), una `score` de vida (0–100) y un `status` `Approved`/`Declined`. La edad la **predice el modelo a partir del rostro y no se verifica contra un documento**: úsala para controles de edad y comprobaciones de baja fricción, no como prueba legal de la edad. **Cómo funciona.** Se analiza la imagen en busca de rostros (establece `rotate_image=true` si las capturas pueden estar de lado o boca abajo); a cada rostro detectado se le asigna una edad estimada, y el rostro más grande del encuadre determina `age_estimation`. En paralelo, un modelo de prueba de vida pasiva puntúa si la foto muestra a una persona real (sin exigir ningún reto al usuario) y detecta ataques de presentación (fotos de fotos, pantallas, máscaras). Para obtener los mejores resultados, envía un único rostro nítido, de frente y bien iluminado por imagen. **Lógica de decisión.** Cualquier advertencia provoca el rechazo: `status` es `Approved` solo cuando el array `warnings` está vacío. Una `score` de vida igual o inferior a `face_liveness_score_decline_threshold` (por defecto `30`) añade `LOW_LIVENESS_SCORE`; un ataque detectado añade `LIVENESS_FACE_ATTACK`; si el modelo de prueba de vida no encuentra ningún rostro, se añade `NO_FACE_DETECTED`; si no se puede estimar la edad de ningún rostro, se añade `AGE_NOT_DETECTED` (`age_estimation` es `null`); una edad estimada inferior a `age_estimation_decline_threshold` (por defecto `18`) añade `AGE_BELOW_MINIMUM`. Para las edades límite cercanas a tu umbral conviene recurrir a una verificación basada en documentos: el error del modelo aumenta en los rostros próximos al límite. **Facturación.** Cada respuesta `200` consume un crédito de la API de Estimación de edad (pagado con el crédito de tu plan o con tu saldo de recarga). Cuando el saldo de la organización no alcanza para cubrir la llamada, el endpoint devuelve `403` con el error de créditos insuficientes antes de procesar ninguna imagen. **Persistencia de la sesión (`save_api_request`, por defecto `true`).** Cuando es `true`, la llamada se guarda como una sesión de tipo API: aparece en la Business Console, el `request_id` devuelto es un id de sesión real que puedes pasar a `GET /v3/session/{sessionId}/decision/` (el resultado se expone ahí en `liveness_checks[]`, con `features: ["AGE_ESTIMATION"]`), se almacenan el recorte del rostro y la imagen de referencia, el embedding facial se añade al índice facial de tu aplicación (que usan la búsqueda facial y la detección de duplicados) y se emite un webhook `status.updated`. Cuando es `false`, no se almacena nada y `request_id` es un UUID de correlación puntual que no se puede consultar después. **Sandbox.** Las claves de API de sandbox omiten todo el procesamiento y la facturación: tras validar la solicitud (una entrada mal formada sigue devolviendo `400`), el endpoint devuelve un payload simulado estático `Approved` (`age_estimation: 30`, sin advertencias), 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 faltan las credenciales 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.** Presupuesto de escritura compartido de 300 solicitudes/min por clave de API entre todos los endpoints POST/PATCH/DELETE; si se supera, se devuelve `429`. operationId: post_v3age-estimation parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image properties: user_image: type: string format: binary description: >- Foto del rostro que se va a analizar (por ejemplo, una selfie). Envía una sola foto de frente en la que el rostro de la persona se vea con claridad y esté bien iluminado. Extensiones permitidas: `tiff`, `jpg`, `jpeg`, `png`, `webp` (no se admite PDF). 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 unos 0,3 MB antes del procesamiento, por lo que las resoluciones muy altas no mejoran la precisión. face_liveness_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Umbral de prueba de vida (0–100). Un `score` de prueba de vida **igual o inferior** a este valor añade una advertencia `LOW_LIVENESS_SCORE` y rechaza. Súbelo para una protección antisuplantación más estricta; los valores fuera de 0–100 devuelven `400`. example: 30 age_estimation_decline_threshold: type: integer default: 18 minimum: 0 maximum: 100 description: >- Edad estimada mínima aceptable, en años. Una edad estimada **inferior** a este valor añade una advertencia `AGE_BELOW_MINIMUM` y rechaza la verificación. Establece `0` para desactivar la comprobación de edad (la llamada solo ejecuta entonces la prueba de vida y la estimación de edad, sin una decisión basada en la edad). example: 18 rotate_image: type: boolean default: false description: >- Si es `true`, el servicio prueba la imagen de entrada en incrementos de 90 grados (0, 90, 180, 270) y usa la orientación que ofrece la mejor detección facial, algo útil para capturas desde el móvil sin orientación EXIF. Añade latencia, así que actívalo solo si no puedes garantizar imágenes en posición vertical. example: false save_api_request: type: boolean default: true description: >- Cuando es `true` (valor predeterminado), guarda la llamada como una sesión de tipo API: visible en la Business Console, recuperable mediante `GET /v3/session/{sessionId}/decision/` con el `request_id` devuelto, notificada mediante un webhook `status.updated` y con el rostro detectado añadido al índice facial de tu aplicación. Cuando es `false`, no se almacena nada y `request_id` es un UUID temporal que solo sirve para correlacionar la respuesta. example: true vendor_data: type: string description: >- Cadena opaca opcional (tu ID de usuario interno, correo electrónico, UUID…) que se guarda en la sesión persistida y se devuelve en la respuesta. Úsala para relacionar las llamadas a la API con tus propios registros y para filtrar sesiones más adelante. 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 la respuesta. En solicitudes multipart, envíalo como un campo de cadena codificado en JSON (p. ej., `metadata={"flow":"age-gate"}`): se convierte en un objeto. example: flow: age-gate example: user_image: (binary JPEG/PNG of the selfie) face_liveness_score_decline_threshold: 30 age_estimation_decline_threshold: 18 rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: age-gate responses: '200': description: >- Estimación de edad y prueba de vida pasiva completadas. `age_estimation.age_estimation` es la edad en años que predice el modelo para el rostro más grande detectado (`null` si no hay ninguno); `age_estimation.score` es la puntuación de la prueba de vida pasiva (0–100); `status` es `Approved` solo cuando `warnings` está vacío. Una captura de un menor de edad o suplantada sigue devolviendo `200` con `status: "Declined"`: revisa el cuerpo, 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 de un adulto — ambas comprobaciones superadas value: request_id: 0c40ba43-64ab-4e2e-b4b8-7d1f12f81bc1 age_estimation: status: Approved method: PASSIVE score: 97.5 user_image: entities: - age: 27.33 bbox: - 40 - 40 - 100 - 100 confidence: 0.7177750468254089 gender: male best_angle: 0 age_estimation: 27.33 warnings: [] vendor_data: user-123 metadata: flow: age-gate created_at: '2026-06-12T02:24:11.512941+00:00' Declined - age below threshold: summary: Edad estimada inferior a `age_estimation_decline_threshold` value: request_id: 9be41a6f-2f4e-4f57-92f4-b3a4f6f0a1c2 age_estimation: status: Declined method: PASSIVE score: 95 user_image: entities: - age: 16.5 bbox: - 40 - 40 - 100 - 100 confidence: 0.7177750468254089 gender: female best_angle: 0 age_estimation: 16.5 warnings: - risk: AGE_BELOW_MINIMUM feature: LIVENESS additional_data: null log_type: error short_description: Age below minimum long_description: >- The age of the face is below the minimum age threshold for the application. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:26:40.118332+00:00' Declined - liveness too low: summary: >- Puntuación de prueba de vida igual o inferior al umbral de rechazo (posible suplantación) value: request_id: 5f6f2f1f-7c4f-43b9-8d62-0a8f4c2d9e77 age_estimation: status: Declined method: PASSIVE score: 5 user_image: entities: - age: 25 bbox: - 40 - 40 - 100 - 100 confidence: 0.7177750468254089 gender: male best_angle: 0 age_estimation: 25 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. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:27:02.901547+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. age_estimation: type: object properties: status: type: string enum: - Approved - Declined description: >- `Approved` cuando no se generó ninguna advertencia; `Declined` en caso contrario (todas las advertencias que produce este endpoint implican un rechazo). method: type: string enum: - PASSIVE description: >- Método de prueba de vida. Siempre `PASSIVE` en este endpoint (una sola imagen, sin desafío para el usuario). score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Puntuación de prueba de vida pasiva de 0 a 100: la confianza del modelo de que la foto muestra a una persona real. Se compara con `face_liveness_score_decline_threshold`; si es igual o inferior, la llamada se rechaza con `LOW_LIVENESS_SCORE`. Es `null` cuando el modelo de prueba de vida no devuelve ninguna confianza; aun así, la llamada se rechaza con `LOW_LIVENESS_SCORE`, porque null se trata como 0 en la comparación con el umbral. example: 97.5 user_image: type: object description: >- Resultados de la detección facial de la imagen analizada. properties: entities: type: array description: >- Una entrada por rostro detectado. Vacío cuando no se encontró ningún rostro (en ese caso `age_estimation` es `null` y se añade una advertencia `AGE_NOT_DETECTED`). items: type: object properties: age: type: number format: float description: >- Edad de este rostro estimada por el modelo, en años. example: 27.33 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: - 40 - 40 - 100 - 100 confidence: type: number format: float minimum: 0 maximum: 1 description: Confianza de la detección facial (0–1). example: 0.7177750468254089 gender: type: string description: >- Género del rostro detectado predicho por el modelo (`male` o `female`). Solo es informativo. example: male best_angle: type: integer nullable: true description: >- Rotación (en grados: 0, 90, 180 o 270) que produjo la mejor detección facial. Solo es distinta de cero cuando `rotate_image=true` corrigió la orientación. example: 0 age_estimation: type: number format: float nullable: true description: >- Edad en años predicha por el modelo para el rostro detectado **más grande**. `null` cuando no se pudo estimar la edad de ningún rostro (se añade una advertencia `AGE_NOT_DETECTED` y la llamada se rechaza). example: 27.33 warnings: type: array description: >- Vacío en una aprobación sin incidencias. Cualquier entrada establece `status` en `Declined`. items: type: object properties: risk: type: string enum: - NO_FACE_DETECTED - LOW_LIVENESS_SCORE - LIVENESS_FACE_ATTACK - AGE_NOT_DETECTED - AGE_BELOW_MINIMUM description: >- Código de riesgo legible por máquina. `NO_FACE_DETECTED`: el modelo de prueba de vida no encontró ningún rostro; `LOW_LIVENESS_SCORE`: la `score` de prueba de vida es igual o inferior a `face_liveness_score_decline_threshold`; `LIVENESS_FACE_ATTACK`: se detectó un ataque de presentación (foto/pantalla/máscara); `AGE_NOT_DETECTED`: no se pudo estimar la edad del rostro; `AGE_BELOW_MINIMUM`: la edad estimada es inferior a `age_estimation_decline_threshold`. `NO_FACE_DETECTED` y `LOW_LIVENESS_SCORE` son mutuamente excluyentes: cuando no se encuentra ningún rostro, solo se emite `NO_FACE_DETECTED`. 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: >- Siempre `null` en las advertencias de estimación de edad. log_type: type: string enum: - error description: >- Gravedad. Todas las advertencias que produce este endpoint son de tipo `error` y establecen `status` en `Declined`. short_description: type: string description: Resumen legible del riesgo en una línea. long_description: type: string description: Explicación legible del riesgo. 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. '400': description: >- Error de validación. Se devuelve cuando falta `user_image`, supera los 5 MB o tiene una extensión no admitida, o cuando un umbral está fuera de rango. El cuerpo es el formato estándar de errores de campo de DRF: un array de mensajes por cada campo con error. content: application/json: examples: Missing user image: summary: '`user_image` no incluido en los datos del formulario' value: user_image: - No file was submitted. 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 Threshold out of range: summary: >- `face_liveness_score_decline_threshold` fuera del rango 0–100 value: face_liveness_score_decline_threshold: - Ensure this value is less than or equal to 100. '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/age-estimation/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'age_estimation_decline_threshold=18' \ -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.age_estimation.estimate( user_image=open("user_image.jpg", "rb"), face_liveness_score_decline_threshold=30.0, age_estimation_decline_threshold=18, rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "age-gate"}, ) 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.ageEstimation.estimate({ user_image: await fileFromPath("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, age_estimation_decline_threshold: 18, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "age-gate" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.AgeEstimation.Estimate(ctx, didit.AgeEstimationEstimateParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tFaceLivenessScoreDeclineThreshold: didit.Float(30.0),\n\tAgeEstimationDeclineThreshold: didit.Int(18),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"age-gate\"}),\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.AgeEstimationEstimateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.ageEstimation().estimate(AgeEstimationEstimateParams.builder() .userImage(Path.of("user_image.jpg")) .faceLivenessScoreDeclineThreshold(30.0) .ageEstimationDeclineThreshold(18L) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "age-gate")) .build()); System.out.println(result); - lang: php label: PHP source: |- ageEstimation->estimate([ 'user_image' => File::fromPath('user_image.jpg'), 'face_liveness_score_decline_threshold' => 30.0, 'age_estimation_decline_threshold' => 18, 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'age-gate'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.age_estimation.estimate( user_image: Pathname("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, age_estimation_decline_threshold: 18, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "age-gate" } ) 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.AgeEstimation.EstimateAsync(new AgeEstimationEstimateParams { UserImage = FileUpload.FromPath("user_image.jpg"), FaceLivenessScoreDeclineThreshold = 30.0, AgeEstimationDeclineThreshold = 18, RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "age-gate" }, }); 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.