> ## 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의 라이브니스 감지 보고서를 확인하세요. 상태, 신뢰도 점수, 감지 방식, 연령 추정, 세션 간 얼굴 대조 결과 및 API 응답 구조를 설명합니다.

## 개요

**라이브니스 보고서**는 카메라 앞에 인쇄된 사진, 화면 재생 또는 딥페이크가 아닌 실제 사람이 있는지 확인하는 동안 Didit이 관찰한 모든 내용을 기록합니다. 여기에는 라이브니스 방식, 0–100점의 신뢰도 점수, 참조 셀피 및 캡처 비디오, 선택적 연령 추정, 패시브 라이브니스 품질 지표, 그리고 애플리케이션의 이력 및 차단 목록과 대조한 교차 세션 얼굴 대조 결과가 포함됩니다.

이 보고서는 사용자가 워크플로에서 라이브니스 단계를 완료하거나(또는 독립 실행형 얼굴 endpoint를 호출한 후) 생성됩니다. Didit은 세 가지 라이브니스 방식(액티브 3D, 플래싱 또는 패시브) 중 하나를 실행하고, 캡처 점수를 산정하며, 알려진 스푸핑 패턴을 검사하고, 애플리케이션에서 확인된 다른 모든 얼굴과 생체 인식 방식으로 비교합니다.

각 보고서는 전체 세션 상태와 무관하게 라이브니스 단계 자체의 처리 결과를 반영하는 자체 `status`를 가집니다.

* **승인됨** — 얼굴이 감지되었고, 라이브니스 점수가 검토 임계값보다 높으며, 자동 거부 경고가 발생하지 않았습니다.
* **검토 중** — 검토로 전달되는 경고가 하나 이상 발생했거나, 점수가 검토 임계값 이하이지만 거부 임계값보다 높습니다.
* **거부됨** — 자동 거부 조건(`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, 또는 연령 추정 흐름의 연령 위험)이 발생했거나, 설정 가능한 경고가 거부로 전달되었거나, 점수가 거부 임계값 이하입니다.
* **완료되지 않음** — 사용자가 라이브니스 단계를 완료하지 않았습니다.

## API 응답에 표시되는 위치

라이브니스 보고서는 `GET /v3/session/{sessionId}/decision/`에서 `liveness_checks[]`로 표시되며, 단일 `liveness` 객체가 아닌 **항상 JSON 배열**로 제공됩니다. 워크플로에서 라이브니스를 두 번 이상 실행하는 경우(예: 기본 검사 후 재캡처) 여러 항목이 표시됩니다.

* **세션 결정 API** — `GET /v3/session/{sessionId}/decision/`은 최상위 수준에서 `liveness_checks[]`를 반환합니다. [세션 결정 조회](https://docs.didit.me/ko/sessions-api/retrieve-session.md)를 참조하세요.
* **Webhook** — 단계에서 데이터가 생성되면 `session.status.updated` payload에 동일한 `liveness_checks[]` 배열이 포함됩니다. [Webhook](https://docs.didit.me/ko/integration/webhooks.md)을 참조하세요.
* **독립 실행형 라이브니스 API** — [라이브니스 독립 실행형 API](https://docs.didit.me/ko/standalone-apis/passive-liveness.md)를 참조하세요.

> [!NOTE]
>
> `response.liveness_checks[0]`을 읽고 배열을 순회하세요. 일부 이전 튜토리얼에서 언급된 단일 `liveness` 형태는 v3 결정 endpoint에 존재하지 않습니다.

## 스키마

필드별 표준 스키마는 [데이터 모델](https://docs.didit.me/ko/reference/data-models.md#라이브니스-검사) 참조 페이지에서 확인할 수 있습니다. 아래 필드들은 해당 표준 스키마를 반영합니다.

| 필드 | 유형 | 설명 |
| - | - | - |
| `status` | `"Approved" \| "Declined" \| "In Review" \| "Not Finished" \| "Resub Requested"` | 라이브니스 단계 상태(아래 참조). |
| `node_id` | string \| null | 이 보고서를 생성한 워크플로 그래프 노드. |
| `method` | `"ACTIVE_3D" \| "FLASHING" \| "PASSIVE"` | 이 캡처를 생성한 라이브니스 방식. |
| `score` | number 0–100 \| null | 라이브니스 신뢰도 점수(소수점 둘째 자리까지 반올림됨). |
| `reference_image` | string (서명된 URL) \| null | 캡처에서 추출한 참조 셀피. 유효 기간이 제한된 서명된 URL. |
| `video_url` | string (서명된 URL) \| null | 전체 라이브니스 캡처 동영상(액티브 방식). 유효 기간이 제한된 서명된 URL. |
| `age_estimation` | number \| null | 참조 이미지에서 가장 큰 얼굴의 추정 연령(년 단위). |
| `face_quality` | number 0–100 \| null | 패시브 라이브니스 얼굴 품질(백분율로 정규화됨). `method = "PASSIVE"`인 경우에만 채워집니다. |
| `face_luminance` | number 0–100 \| null | 패시브 라이브니스 얼굴 밝기(0–255에서 백분율로 정규화됨). `method = "PASSIVE"`인 경우에만 채워집니다. |
| `matches[]` | array | 세션 간 얼굴 대조 결과(아래 참조). |
| `warnings[]` | array | 모듈 수준 경고 — [라이브니스 경고](https://docs.didit.me/ko/core-technology/liveness/warnings-liveness.md)를 참조하십시오. 각 항목은 [경고 객체](https://docs.didit.me/ko/reference/data-models.md#경고-객체) 형태(`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`)를 따릅니다. |

### 세션 간 얼굴 대조

`matches[]`는 해당 셀피에 대해 생체 인식 유사도 임계값을 초과한 애플리케이션 내역의 얼굴 목록을 표시합니다. 차단 목록 및 허용 목록의 얼굴이 먼저 표시되며, 이후 유사도 내림차순으로 최대 5개 항목까지 제공됩니다. 대상 후보는 차단 목록의 얼굴, 허용 목록의 얼굴, `Approved` 세션의 얼굴, 그리고 벤더 사용자로 가져온 얼굴입니다. 동일한 사용자(동일한 `vendor_data` 또는 사용 가능한 경우 동일한 벤더 사용자)에 속한 얼굴은 중복 감지 및 차단 목록 스크리닝을 포함한 **전체** 검색에서 제외됩니다.

각 항목에는 다음이 포함됩니다:

| 필드 | 유형 | 설명 |
| - | - | - |
| `session_id` | string (UUID) \| null | 일치하는 세션. `source`가 `imported` 또는 `list_entry`인 경우 `null`. |
| `session_number` | number \| null | 일치하는 세션의 순차 세션 번호. 세션이 아닌 출처의 경우 `null`. |
| `similarity_percentage` | number 0–100 | 생체 인식 유사도 점수(0–100 범위로 고정). |
| `vendor_data` | string \| null | 일치하는 세션의 참조 데이터(가져온 얼굴의 경우 벤더 사용자 데이터). |
| `verification_date` | string (ISO 8601) \| null | 일치하는 세션(또는 가져온 얼굴)이 생성된 시점. |
| `user_details` | object \| null | 일치하는 세션의 KYC에서 가져온 `{ full_name, document_type, document_number }`. 가져온 얼굴은 `full_name`만 채워집니다(두 문서 필드는 `null`). 기록된 세부 정보가 없으면 `null`입니다. |
| `match_image_url` | string (서명된 URL) \| null | 일치하는 세션, 가져온 얼굴 또는 목록 항목의 참조 얼굴. |
| `status` | string \| null | 일치하는 세션의 상태(예: `"Approved"`). 세션이 아닌 출처의 경우 `null`. |
| `is_blocklisted` | boolean | 일치하는 얼굴이 얼굴 차단 목록에 있는 경우 `true`. |
| `is_allowlisted` | boolean | 일치하는 얼굴이 얼굴 허용 목록에 있는 경우 `true`(중복 얼굴에 대한 작업이 건너뛰어집니다). |
| `api_service` | string \| null | 일치하는 얼굴이 독립형 API 호출에서 나온 경우 설정됨(예: `"PASSIVE_LIVENESS"`). 워크플로 세션 및 세션이 아닌 출처의 경우 `null`. |
| `source` | `"session" \| "imported" \| "list_entry"` | 일치하는 얼굴의 출처: 다른 인증 세션, 벤더 사용자에 업로드된 얼굴, 조직에서 관리하는 허용/차단 목록 얼굴. |

## 상태 값

상태 값은 공유 기능 상태 열거형(`FeatureStatusChoices`)에서 가져옵니다.

| 상태 | 의미 | 후속 영향 |
| - | - | - |
| `Approved` | 얼굴이 감지되었고, 라이브니스 점수가 검토 임계값을 초과했으며, 자동 거부 경고가 발생하지 않았습니다. | 성공한 라이브니스 검사로 간주됩니다. |
| `In Review` | 점수가 검토 임계값 이하이지만 거부 임계값을 초과했거나, 검토로 라우팅된 경고가 발생했습니다. | 검토자가 조치를 취할 때까지 세션도 `In Review` 상태로 전환됩니다. |
| `Declined` | 자동 거부 위험(`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST` 또는 연령 추정 플로우의 연령 위험)이 발생했거나, 구성 가능한 경고가 거부로 라우팅되었거나, 점수가 거부 임계값 이하입니다. | 승인된 다른 분기가 워크플로를 충족하지 않는 한 세션이 거부됩니다. |
| `Not Finished` | 사용자가 라이브니스 단계를 중단했거나(또는 재시도 가능한 캡처 실패 후 추가 시도를 대기 중임). | 라이브니스 분기에서 결과를 생성하지 못했습니다. |
| `Resub Requested` | 검토자가 콘솔에서 이 단계의 재제출을 요청했습니다. | 일시적 상태 — 사용자가 다시 캡처하면 대체됩니다. |

## 예시

### Approved — 이상 없는 액티브 3D 캡처

```json theme={null}
{
  "liveness_checks": [
    {
      "status": "Approved",
      "node_id": "liveness_primary",
      "method": "ACTIVE_3D",
      "score": 92.4,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": "https://<media-host>/.../liveness.mp4?signature=...",
      "age_estimation": 24.3,
      "face_quality": null,
      "face_luminance": null,
      "matches": [],
      "warnings": []
    }
  ]
}
```

### In Review — 패시브 라이브니스, 낮은 캡처 품질 및 잠재적 중복

```json theme={null}
{
  "liveness_checks": [
    {
      "status": "In Review",
      "node_id": "liveness_primary",
      "method": "PASSIVE",
      "score": 76.1,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": null,
      "age_estimation": 31.0,
      "face_quality": 12.4,
      "face_luminance": 18.7,
      "matches": [
        {
          "session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
          "session_number": 123,
          "similarity_percentage": 96.8,
          "vendor_data": "user-555",
          "verification_date": "2024-07-15T10:23:45Z",
          "user_details": {
            "full_name": "John Smith",
            "document_type": "Passport",
            "document_number": "SAMPLE-DOC-12345"
          },
          "match_image_url": "https://<media-host>/.../matched.jpg?signature=...",
          "status": "Approved",
          "is_blocklisted": false,
          "is_allowlisted": false,
          "api_service": null,
          "source": "session"
        }
      ],
      "warnings": [
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_QUALITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face quality",
          "long_description": "The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_LUMINANCE",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face luminance",
          "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "POSSIBLE_DUPLICATED_FACE",
          "additional_data": {
            "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
            "duplicated_session_number": 123,
            "api_service": null
          },
          "log_type": "warning",
          "short_description": "Possible duplicated face from other approved session",
          "long_description": "The system identified a possible duplicate face from another approved session, requiring further investigation.",
          "node_id": "liveness_primary"
        }
      ]
    }
  ]
}
```

여기서 얼굴 품질(12.4)은 기본 검토 임계값(15) 미만이고, 밝기(18.7)는 기본 최소값(20) 미만이며, 워크플로의 중복 얼굴 작업이 검토로 설정되어 있습니다. 따라서 세 가지 경고 모두 `log_type: "warning"`을 가지며 보고서는 `In Review`로 결정됩니다.

## 보안 참고 사항

라이브니스 동영상과 셀피는 생체 인식 데이터입니다. 서명된 URL은 일시적이며 만료됩니다(기본 4시간 후). 단기간만 유효한 것으로 취급해야 하며, 캐시하거나 외부에 공개해서는 안 됩니다. 일반적으로 애플리케이션에는 `status`, `score` 및 경고만 필요합니다. 서버에 저장되는 생체 인식 데이터를 최소화하기 위해 가능한 한 적은 데이터만 저장하십시오.

## 관련 항목

* [라이브니스 경고](https://docs.didit.me/ko/core-technology/liveness/warnings-liveness.md) — 전체 경고 열거형, 발생 원인 및 해결 방법.
* [webhook](https://docs.didit.me/ko/integration/webhooks.md) — 보고서를 수신하려면 `session.status.updated` 이벤트를 수신 대기합니다.
* [데이터 모델 — 라이브니스 검사](https://docs.didit.me/ko/reference/data-models.md#라이브니스-검사) — 모든 필드가 포함된 표준 스키마.
* [얼굴 대조 보고서](https://docs.didit.me/ko/core-technology/face-match/report-face-match.md) — 문서 인물 사진과 1:1로 대조하는 함께 제공되는 얼굴 대조.


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