연령 추정 경고 및 위험 코드

연령 추정 기능은 연령 및 수동적 라이브니스 결합 검사에서 위험 신호가 발생할 때마다 경고를 생성합니다. 즉, 예측된 연령이 최소 연령 미만이거나, 연령을 계산할 수 없거나, 대상자가 라이브니스 검사에 실패했거나, 얼굴을 찾을 수 없거나, 프레젠테이션 공격이 감지된 경우입니다. 이 페이지에는 모든 코드, 트리거 조건 및 워크플로 응답 구성 방법이 안내되어 있습니다.

개요

연령 추정은 항상 한 번의 호출로 두 가지 검사(수동적 라이브니스 테스트 및 연령 회귀 모델)를 실행하므로, 해당 경고는 공유 라이브니스 파이프라인을 거치며 LIVENESS 기능 태그가 지정됩니다. 이러한 경고는 보고서의 age_estimation.warnings[](독립형 API) 또는 liveness_checks[].warnings[](워크플로에 임베드된 경우) 아래에 표시됩니다. 경고 객체 스키마는 데이터 모델 — 경고 객체에 설명되어 있습니다. 생성 주체:

독립형 API — endpoint는 거부 트리거 아래에 나열된 5가지 경고를 생성합니다.
워크플로 — 공유 라이브니스 생성 주체 및 연령별 검사가 포함됩니다. 연령 경고는 연령 추정 플로우(적응형 연령 확인 워크플로 또는 AGE_ESTIMATION 워크플로 노드)에서만 발생하며, 일반 라이브니스 단계에서는 추정 연령을 보고하지만 연령 경고를 발생시키지는 않습니다.

심각도: 5가지 자동 거부 위험(NO_FACE_DETECTED, LIVENESS_FACE_ATTACK, FACE_IN_BLOCKLIST, AGE_BELOW_MINIMUM, AGE_NOT_DETECTED)은 항상 log_type: "error"이며 강제로 Declined를 발생시킵니다. 나머지 위험은 임계값 또는 구성된 작업에 따라 error / warning / information으로 처리됩니다.

거부 트리거

독립형 API에서는 어떠한 경고라도 발생하면 결정이 Declined로 처리됩니다:

임계값 미만의 연령 — 예측된 연령이 age_estimation_decline_threshold 미만임(기본값 18, 0은 연령 검사 비활성화). AGE_BELOW_MINIMUM을 발생시킵니다.
연령 계산 불가 — 얼굴에서 연령을 추정할 수 없음(감지 가능한 얼굴이 없거나 연령 모델에 사용할 수 있는 얼굴이 없음). AGE_NOT_DETECTED를 발생시킵니다.
임계값 이하의 라이브니스 점수 — score <= face_liveness_score_decline_threshold(기본값 30), null 점수는 0으로 처리됩니다. LOW_LIVENESS_SCORE를 발생시킵니다. NO_FACE_DETECTED가 발생하면 생략됩니다(두 항목은 상호 배타적임).
얼굴 감지 안 됨 — 라이브니스 모델이 얼굴을 찾지 못했습니다. NO_FACE_DETECTED를 발생시킵니다.
프레젠테이션 공격 — 라이브니스 모델이 화면, 인쇄된 사진, 마스크 또는 기타 스푸핑을 감지했습니다. LIVENESS_FACE_ATTACK을 발생시킵니다.

워크플로에서 연령 검사는 소수점 이하를 버린 추정 연령(정수 연령)을 구성된 임계값과 비교합니다:

신분증 인증 대체 기능 활성화 시(enable_id_verification_fallback, 기본 활성화): borderline_minimum_age_threshold(기본값 18) 미만의 연령은 AGE_BELOW_MINIMUM을 발생시킵니다. 경계 구간의 연령(borderline_maximum_age_threshold 이하)은 경고를 발생시키는 대신 문서 확인으로 진행되며, AGE_NOT_DETECTED는 절대 발생하지 않고 감지되지 않은 연령도 문서 확인으로 라우팅됩니다.
대체 기능 비활성화 시: 추정 연령이 없으면 AGE_NOT_DETECTED를 발생시키고, minimum_age_threshold(기본값 18) 미만의 연령은 AGE_BELOW_MINIMUM을 발생시킵니다.

설정 가능한 위험

다음 위험 항목들을 통해 워크플로 설정별로 임계값이나 작업을 세부 조정할 수 있습니다:

Setting	Risk code	Configurable options
Age thresholds	`AGE_BELOW_MINIMUM`	Standalone: `age_estimation_decline_threshold` (default `18`, `0` disables). Workflows: `minimum_age_threshold` / `borderline_minimum_age_threshold` (default `18`) plus the ID-verification fallback for borderline ages.
Low Liveness Score	`LOW_LIVENESS_SCORE`	Separate Decline threshold (default `30` → `error` + decline) and Review threshold (default `60` → `warning` + review) applied against the liveness score.
Possible Duplicated Face	`POSSIBLE_DUPLICATED_FACE`	Action on detection: `DECLINE` / `REVIEW` / `NO_ACTION` (default `NO_ACTION`). Workflow sessions only.
Multiple Faces	`MULTIPLE_FACES_DETECTED`	Action on detection: `DECLINE` / `REVIEW` / `NO_ACTION` (default `NO_ACTION`). Workflow passive liveness only.

워크플로 세션은 또한 귀하의 목록을 기준으로 얼굴을 스크리닝합니다. FACE_IN_BLOCKLIST는 항상 자동으로 거부(error)하며, POSSIBLE_FACE_IN_BLOCKLIST는 세션을 In Review로 이동시킵니다.

생성되는 경고

태그	심각도 (`log_type`)	설명
`AGE_BELOW_MINIMUM`	`error` — 자동 거부	추정 연령이 활성 임계값(독립형 `age_estimation_decline_threshold`, 워크플로 `minimum_age_threshold` / `borderline_minimum_age_threshold`, 모두 기본값 `18`) 미만입니다. `additional_data`는 항상 `null`입니다.
`AGE_NOT_DETECTED`	`error` — 자동 거부	얼굴 연령을 추정할 수 없습니다. 연령이 `null`일 때 독립형 API에서 항상 발생하며, 워크플로에서는 신분증 인증 폴백이 비활성화된 경우에만 발생합니다.
`LOW_LIVENESS_SCORE`	거부 임계값 이하일 때 `error`, 검토 임계값 이하일 때 `warning`	라이브니스 점수가 설정된 임계값(독립형 및 워크플로 거부 기본값 `30`, 워크플로 검토 기본값 `60`) 이하이며, 정적 사진, 화면 또는 동영상을 사용했을 가능성이 있음을 나타냅니다. `NO_FACE_DETECTED`가 트리거된 경우에는 발생하지 않습니다.
`NO_FACE_DETECTED`	`error` — 자동 거부	제출된 이미지에서 얼굴이 감지되지 않았습니다. 적절한 조명 아래에서 카메라 중앙에 얼굴을 맞추도록 사용자에게 다시 요청하세요.
`LIVENESS_FACE_ATTACK`	`error` — 자동 거부	라이브니스 모델이 프레젠테이션 공격(화면 재생, 인쇄된 사진, 가면, 딥페이크)을 감지했습니다.
`MULTIPLE_FACES_DETECTED`	설정된 작업에 따름(기본값 `information`, 작업 없음)	이미지에서 둘 이상의 얼굴이 발견되었습니다. 가장 큰 얼굴을 기준으로 결과가 결정됩니다. 워크플로 패시브 라이브니스에만 해당하며 독립형 API에서는 발생하지 않습니다.
`FACE_IN_BLOCKLIST`	`error` — 자동 거부	감지된 얼굴이 Lists API를 통해 관리되는 얼굴 차단 목록의 항목과 일치합니다. 워크플로 세션에만 해당합니다.
`POSSIBLE_DUPLICATED_FACE`	설정된 작업에 따름(기본값 `information`, 작업 없음)	감지된 얼굴이 다른 세션에서 이전에 승인된 얼굴과 매우 유사합니다(동일한 `vendor_data`를 공유하는 일치 항목은 제외됩니다). 워크플로 세션에만 해당합니다.

예시

{
  "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": "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."
    }
  ]
}

워크플로 결정 payload(liveness_checks[].warnings[])에서 각 경고에는 이를 생성한 워크플로 노드를 식별하는 node_id도 포함됩니다.

경고 유형

각 위험에는 애플케이션 설정에 따라 심각도가 할당됩니다. 심각도는 세 가지 범주로 나뉩니다.

인증

인증

모니터링

플랫폼

연령 추정 경고 및 위험 코드

개요

거부 트리거

설정 가능한 위험

생성되는 경고

예시

경고 유형

관련 항목

​개요

​거부 트리거

​설정 가능한 위험

​생성되는 경고

​예시

​경고 유형

​관련 항목

개요

거부 트리거

설정 가능한 위험

생성되는 경고

예시

경고 유형

관련 항목