> ## 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.

# 연령 추정 경고 및 위험 코드

> Didit 연령 추정의 각 위험 코드(AGE_BELOW_MINIMUM, AGE_NOT_DETECTED, LOW_LIVENESS_SCORE, NO_FACE_DETECTED)별 임계값과 권장 작업 레퍼런스입니다.

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

## 개요

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

생성 주체:

* **독립형 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](https://docs.didit.me/ko/management-api/lists/overview.md)를 통해 관리되는 얼굴 차단 목록의 항목과 일치합니다. 워크플로 세션에만 해당합니다. |
| `POSSIBLE_DUPLICATED_FACE` | 설정된 작업에 따름(기본값 `information`, 작업 없음) | 감지된 얼굴이 다른 세션에서 이전에 승인된 얼굴과 매우 유사합니다(동일한 `vendor_data`를 공유하는 일치 항목은 제외됩니다). 워크플로 세션에만 해당합니다. |

## 예시

```json theme={null}
{
  "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`도 포함됩니다.

## 경고 유형

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

## 관련 항목

* [연령 추정 개요](https://docs.didit.me/ko/core-technology/age-estimation/overview.md) — 기능 동작 방식, 요금 및 결정 로직.
* [연령 추정 보고서](https://docs.didit.me/ko/core-technology/age-estimation/report-age-estimation.md) — 독립형 API 및 임베디드 워크플로 값 모두에 대한 전체 응답 형태.
* [독립형 API 참조](https://docs.didit.me/ko/standalone-apis/age-estimation.md) — `POST /v3/age-estimation/` 요청 및 응답.
* [패시브 라이브니스](https://docs.didit.me/ko/core-technology/liveness/overview.md) — 연령 추정 응답에 사용되는 공유 라이브니스 모델.
* [데이터 모델 — 연령 추정](https://docs.didit.me/ko/reference/data-models.md#연령-추정) — 필드별 표준 스키마.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.