> ## 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: 딥페이크 방지
> 패시브 및 액티브 라이브니스로 딥페이크, 마스크, 프레젠테이션 공격을 탐지합니다. Didit 제공. 정확도 99.9%, iBeta 테스트 완료, 호출당 $0.10부터.
Didit 라이브니스 감지는 실제로 살아 있는 사람이 카메라 앞에 있는지 확인합니다. 인쇄된 사진, 화면 재생, 마스크, 딥페이크를 구별하며, 수동형, 3D 액션, 플래시 방식의 라이브니스를 사용합니다. **99.9% 정확도**에 도달하며, 오인 수락률(FAR)은 **0.1% 미만**입니다.
라이브니스 연동 프롬프트
프롬프트를 클립보드에 복사
\
\````# Goal
Integrate Didit Liveness Detection (passive / 3D-action / flashing) into your app. Pick ONE mode.
\# Mode A — Session-based
Use this when the user goes through a hosted Didit flow (SDK or session.url). The workflow's LIVENESS feature controls which method runs.
1\. Configure the workflow's liveness method — `face_liveness_method`: "PASSIVE" | "ACTIVE_3D" | "FLASHING" (Business Console or POST /v3/workflows/).
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open session.url for the user (or mount the Web/Mobile SDK).
4\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.
Decision surface: `liveness_checks[]` array on the decision payload (one entry per liveness node).
\# Mode B — Standalone API (server-to-server, passive only)
Use when you already have a captured selfie and want a one-shot passive-liveness check.
POST https://verification.didit.me/v3/passive-liveness/
multipart/form-data — x-api-key: YOUR_API_KEY
Required: user_image (jpg/jpeg/png/tiff/webp, max 5 MB; PDFs not accepted).
curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/passive-liveness/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```
Returns: { request_id, liveness: { status, method: "PASSIVE", score, user_image: { entities, best_angle }, warnings, face_quality, face_luminance } }.
When `save_api_request=true` the submitted face is also screened against your blocklist and face index for duplicates — set to `false` to skip enrolment.
\# Status enum (per liveness_checks[].status or liveness.status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"
\# Warnings (LogWarningChoices.LIVENESS)
warnings[] risk codes include:
LOW_LIVENESS_SCORE, NO_FACE_DETECTED, LIVENESS_FACE_ATTACK, MULTIPLE_FACES_DETECTED, FACE_IN_BLOCKLIST, POSSIBLE_FACE_IN_BLOCKLIST, DUPLICATED_FACE, POSSIBLE_DUPLICATED_FACE.
Full catalogue: /core-technology/liveness/warnings-liveness.
\# Failure modes to handle
\- HTTP 403 — out of credits.
\- HTTP 400 — missing user_image, file too large, unsupported extension.
\- status="Declined" with LIVENESS_FACE_ATTACK or LOW_LIVENESS_SCORE — presentation attack suspected; do not approve.
\- FACE_IN_BLOCKLIST / DUPLICATED_FACE — block or route to manual review per your policy.
\- NO_FACE_DETECTED / MULTIPLE_FACES_DETECTED — ask the user to retry with a single, well-framed face.
\# See also
\- Canonical schema: /reference/data-models#liveness-check
\- Per-feature report: /core-technology/liveness/report-liveness
\- Risk catalogue: /core-technology/liveness/warnings-liveness
\- Full integration playbook: /integration/integration-prompt````
\
붙여넣을 곳
Didit Academy의 호스팅 사용자 흐름 강의는 8:49에 라이브니스 셀피를 다루고, 9:16부터 수동형, 3D 플래시, 3D 액션 방식을 차례로 설명합니다.[라이브니스 셀피 — Didit Academy](https://www.youtube.com/embed/LzGe-dMWjUw?start=529\&rel=0\&playsinline=1)## 라이브니스 감지 방법당사 플랫폼은 서로 다른 보안 요구와 사용자 경험에 맞춘 세 가지 스푸핑 방지 기술을 구현합니다.
| 방식 |
설명 |
보안 수준 |
적합한 용도 |
| **`3D Action & Flash`** |
• 다중 요소 생체 인증을 **무작위 동작 시퀀스**와 **동적 빛 패턴 분석**과 결합합니다.\
• 시작 시 사용자에게 **눈 깜빡임**이나 **고개 끄덕임** 같은 간단한 동작을 요청하여 실시간 상호작용을 보장합니다.\
• 동시에 시스템은 얼굴에 빛 패턴 시퀀스를 투사하고, **반사광**을 분석하여 얼굴의 입체 구조를 확인합니다.\
• **딥러닝 알고리즘**이 미세 표정과 빛 반사 반응을 분석하여 실제 사람이 있는지 확인합니다.\
• 행동(동작) 신호와 물리적(빛 기반 깊이) 신호를 함께 사용하여 **가장 높은 보안**을 제공하며, 정지 이미지, 동영상, 고급 마스크로도 스푸핑하기가 사실상 불가능합니다.
|
최고 |
금융, 의료, 공공 기관 애플리케이션 |
| **`3D Flash`** |
• 사용자 상호작용 없이 **동적 빛 패턴 분석**을 사용하여 얼굴 형태를 검증합니다.\
• 초당 **30 프레임 이상**으로 얼굴에 일련의 빛 패턴을 투사하고, 반사광을 분석하여 **깊이 맵**을 생성합니다.\
• 이 깊이 맵은 얼굴의 입체 구조를 확인하여 평면 이미지나 2D 스푸프와 구별합니다.\
• 사진이나 화면 같은 프레젠테이션 공격에 대해 **높은 보안**을 유지하면서 **끊김 없는 경험**을 제공합니다.\
|
높음 |
금융 서비스, 계정 접근, 신원 확인 |
| **`Passive Liveness`** |
• **단일 프레임 딥러닝 분석**에 의존하여 라이브니스 징후를 감지합니다.\
• 이미지에서 **아티팩트**, **텍스처 패턴**, 그리고 실제 얼굴과 스푸프를 구별하는 기타 미세한 지표를 살펴봅니다.\
• **합성곱 신경망(CNN)**이 얼굴 특징을 검증하고, 인쇄 사진이나 디지털 화면에서 나온 것과 같은 이상 징후를 식별합니다.\
• **빠르고 편리한** 검증을 제공하지만 **표준 보안** 수준이므로 위험도가 낮은 사용 사례에 적합합니다.\
|
표준 |
사용자 불편이 적은 시나리오, 소비자 애플리케이션 |
> [!NOTE]
>
> **3D Flash 및 3D Action & Flash의 고급 보안:**
>
> > * 이 방식들은 **고품질 마스크**, **딥페이크**, **동영상 재생** 같은 **정교한 스푸핑 공격**을 막도록 설계되었습니다.
> > * 동적 빛 패턴을 투사하고 그 반사광을 분석하여, 빛이 **실제 3D 얼굴**과 평평하거나 인위적인 표면에서 어떻게 상호작용하는지 감지합니다.
> > * **3D Action & Flash** 방식은 무작위 동작(예: 눈 깜빡임 또는 고개 끄덕임)으로 추가 보안 계층을 더하며, 사전 녹화된 미디어나 합성 신원이 복제할 수 없는 **실시간 행동 반응**을 요구합니다.
> > * **높은 정확도**와 **낮은 오인 수락률**을 입증하였으며, 이 방식들은 중요도가 높은 환경에 적합합니다.각 방식은 자체 알고리즘을 기반으로 **정규화된 라이브니스 점수(0-100%)**를 생성하며, 이 알고리즘은 실시간으로 여러 보안 요소를 평가합니다.### 구성 가능한 임계값라이브니스 점수에 서로 다른 임계값을 설정하여 보안 수준을 조정할 수 있습니다. 예를 들면 다음과 같습니다.> [!NOTE]
>
> 이 임계값은 **위험 허용 수준**과 **보안 요구 사항**에 따라 조정할 수 있으며, 다양한 사용 사례에 맞게 유연하게 적용할 수 있습니다.## 재시도 및 조치 가능한 피드백Didit 세션에서 **수정 가능한 이유**(조명 부족, 얼굴 위치 어긋남, 가림, 경계값에 가까운 점수 등)로 라이브니스 캡처가 실패하면 즉시 거부되지 않습니다. 사용자에게 **구체적인 안내와 함께 재시도**를 요청하며, 재시도 횟수는 설정할 수 있습니다.* **시도 횟수**: `face_liveness_max_attempts`는 세션당 라이브니스 제출의 총 횟수를 제어합니다. 기본값은 **3**(최초 시도 1회와 재시도 2회)이며, 워크플로 노드별로 설정할 수 있습니다(범위 1\~3).
* **재시도 피드백**: 시도 횟수가 남아 있는 동안 재시도 가능한 실패가 발생하면 사용자는 라이브니스 단계에 머무르며, 조치 가능한 `feedback_codes`가 포함된 본문이 반환됩니다(Web 및 Mobile SDK는 이를 안내 메시지로 자동 표시합니다):
```json theme={null}
{
"detail": "Move to a brighter, evenly lit place and try again.",
"error": "LOW_FACE_LUMINANCE",
"feedback_codes": ["LOW_FACE_LUMINANCE"],
"attempts_used": 1,
"max_attempts": 3
}
```
* **재시도 가능 코드**: `LOW_FACE_LUMINANCE`(너무 어두움), `HIGH_FACE_LUMINANCE`(너무 밝음), `NO_FACE_DETECTED`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION`, `LOW_LIVENESS_SCORE`, `MULTIPLE_FACES_DETECTED`, `AGE_NOT_DETECTED`.
* **캡처 조건에 대한 보장된 재시도**: `LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION`, `NO_FACE_DETECTED`는 사람이 아니라 사용자가 서 있는 공간의 상태를 나타냅니다. 시도가 이 코드로만 실패하면, `face_liveness_max_attempts: 1`로 구성된 워크플로에서도 사용자는 항상 위의 안내 메시지와 함께 두 번째 시도를 받게 됩니다. 그 밖의 모든 코드는 구성된 시도 횟수를 정확히 따릅니다.
* **시도 소진 및 사기 대응**: 시도 횟수를 모두 사용하면 계산된 상태가 적용됩니다(`Declined` 또는 `In Review`). 확인된 프레젠테이션 공격(`LIVENESS_FACE_ATTACK`), 차단 목록 일치, 중복 얼굴은 **즉시 거부**되며 재시도되지 않습니다.> [!NOTE]
>
> 재시도는 **세션 흐름**에만 적용됩니다. 단독으로 사용하는 `POST /v3/passive-liveness/` 엔드포인트는 상태를 저장하지 않으며 단일 요청으로 동작합니다. 재시도 시도 횟수가 없고 결과를 바로 반환합니다.## 작동 방식**1. 비디오 셀피 캡처**사용자는 선택한 라이브니스 방식에 맞춘 **간단하고 직관적인 인터페이스**를 따라 진행합니다.| 확인 항목 | 설명 |
| - | - |
| **실시간 피드백** | 적절한 조명, 위치, 프레이밍을 보장합니다 |
| **품질 검사** | 흐림, 반사광, 얼굴이 최적으로 보이는지 모니터링합니다 |
| **적응형 캡처** | 다양한 기기 성능과 네트워크 상태에 맞춰 조정합니다 |
| **방식별 안내** | 방식에 맞는 지침을 보여줍니다(예: 3D 액션의 "지금 눈을 깜빡이세요") |**2. 라이브니스 감지 분석**고급 알고리즘이 캡처된 미디어를 **실시간**으로 처리하여 스푸핑 시도를 감지합니다. 분석은 방식에 따라 다릅니다:> [accordion] 3D 액션 및 플래시
>
> * 사용자의 동작(예: **눈 깜빡임** 또는 **고개 끄덕임**)이 올바르게 수행되었고 실제 사람에 의해 이루어졌는지 확인합니다
> * **빛 패턴 반사**를 분석하여 얼굴의 입체 구조를 검증합니다
> * 딥러닝을 사용해 **미세 표정**과 기타 행동 신호를 평가합니다
> * 행동 신호와 물리적 신호를 결합하여 **가장 강력한 스푸핑 저항성**을 제공합니다> [accordion] 3D 플래시
>
> * 30+ FPS에서 일련의 **빛 패턴 반사**를 처리하여 상세한 **깊이 맵**을 생성합니다
> * 얼굴의 3D 특성을 확인하여 평면 또는 2D 스푸핑과 구별합니다
> * 사용자 상호작용이 필요하지 않으며, 사용자 입장에서는 **완전히 수동적으로** 진행됩니다> [accordion] 패시브 라이브니스
>
> * 단일 프레임에 **딥러닝**을 적용하여 **질감 패턴**과 **아티팩트**를 감지합니다
> * 합성곱 신경망(CNN)이 얼굴 특징을 검증하고 이상 징후를 식별합니다
> * 가장 빠른 방식이며, **단일 사진 캡처**로 동작합니다다중 계층 감지는 사진, 화면, 마스크, 딥페이크를 포함한 **프레젠테이션 공격**을 식별합니다.**3. 결과 처리 및 검증**시스템은 라이브니스 점수를 **설정된 임계값**과 비교하고 결과를 즉시 전달합니다.| 출력 | 설명 |
| - | - |
| **라이브니스 점수** | 0\~100%로 정규화된 신뢰도 점수 |
| **결정** | 임계값에 따른 승인됨, 거부됨 또는 검토 중 |
| **메서드** | 사용된 라이브니스 방식(`passive`, `flash`, `action_flash`) |
| **참조 이미지** | 라이브니스 검사에 사용된 캡처 프레임 |
| **경고** | 감지된 이상 징후(예: 낮은 품질, 잠재적 스푸핑 지표) |결과는 **API 응답**, **webhook**으로 전달되거나, 컴플라이언스를 위한 상세한 **감사 로그**와 함께 **비즈니스 콘솔**에서 확인할 수 있습니다.> [!TIP]
>
> [비즈니스 콘솔](https://docs.didit.me/ko/console/workflows.md)에서 워크플로별로 사용할 라이브니스 방식을 설정할 수 있습니다. 위험 요건에 따라 워크플로마다 다른 방식을 사용할 수 있습니다.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.