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

# 얼굴 대조 1:1 API: 셀피 및 신분증 사진 비교

> Didit의 AI 안면 인식으로 라이브 셀피와 신분증 사진을 비교하세요. 호출당 $0.05, 매월 $10 무료 제공, KYC 및 온보딩을 위해 2초 미만으로 일치 점수를 반환합니다.

Didit 얼굴 대조는 두 얼굴을 1:1로 비교하며, 일반적으로 라이브니스 감지에서 촬영한 셀피와 사용자의 신분증에 있는 인물 사진을 비교하여 0에서 100 사이의 유사도 점수를 반환합니다. 설정한 임계값에 따라 검증 통과 여부가 결정되며, 독립형 `POST /v3/face-match/` API는 기본적으로 30점 이하의 점수를 거부합니다.인증 결과 확인에 관한 Academy 강의 중 6:16 챕터에서 실제 세션 내의 얼굴 대조 검사를 다룹니다.[얼굴 대조 — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=376\&rel=0\&playsinline=1)

얼굴 대조 연동 프롬프트
        프롬프트를 클립보드에 복사



      
      

\<pre>

\````# Goal
Integrate Didit Face Match (1:1 — compare two faces) into your app. Pick ONE mode.

\# Mode A — Session-based
Use this when the user goes through a hosted Didit flow. Face Match runs alongside ID Verification (uses the document portrait as ref) and Liveness (uses the live selfie as user_image).

1\. Add the FACE_MATCH feature to a workflow that also runs ID_VERIFICATION + LIVENESS (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: `face_matches[]` array on the decision payload.

\# Mode B — Standalone API (server-to-server)
Use when you already have two images and want a one-shot 1:1 similarity score.

POST https://verification.didit.me/v3/face-match/
multipart/form-data — x-api-key: YOUR_API_KEY

Required: `user_image` (live capture) and `ref_image` (reference portrait). JPEG/PNG/WebP/TIFF, max 5 MB each.

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/face-match/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'ref_image=@./id_portrait.jpg' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```
Returns: { request_id, face_match: { status, score (0-100), user_image: {entities}, ref_image: {entities}, warnings: [...] } }. `status` is "Approved" when score > face_match_score_decline_threshold (default 30), else "Declined".

\# Status enum (per face_matches[].status / face_match.status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"

\# Warnings (LogWarningChoices.FACEMATCH)
warnings[] risk codes include:
LOW_FACE_MATCH_SIMILARITY, NO_REFERENCE_IMAGE, NO_FACE_DETECTED, MULTIPLE_FACES_DETECTED.
Full catalogue: /core-technology/face-match/warnings-face-match.

\# Failure modes to handle
\- HTTP 403 — out of credits.
\- HTTP 400 — missing user_image or ref_image, file too large, unsupported extension.
\- status="Declined" with LOW_FACE_MATCH_SIMILARITY — the two faces do not match; do not approve.
\- NO_REFERENCE_IMAGE / NO_FACE_DETECTED — capture problems; ask the user to retry.

\# See also
\- Canonical schema: /reference/data-models#face-match
\- Per-feature report: /core-technology/face-match/report-face-match
\- Risk catalogue: /core-technology/face-match/warnings-face-match
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

붙여넣을 곳

![신분증 인증 단계 개요](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/id-verification-steps.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=42c64546f3495000d7ea3b10c4b5fa50)## 재시도 및 실행 가능한 피드백Didit 세션에서 **해결 가능한 촬영 문제**(셀피가 너무 어둡거나 흐림, 중심에서 벗어남, 또는 유사도가 경계선에 걸침)로 얼굴 대조에 실패한 경우 즉시 거부되지 않습니다. [라이브니스 감지](https://docs.didit.me/ko/core-technology/liveness/overview.md)에 사용되는 것과 동일한 모델로, 사용자는 설정 가능한 시도 횟수 내에서 **안내와 함께 재시도**하도록 요청받습니다.* **시도 횟수 한도** — `face_match_max_attempts`는 세션당 얼굴 대조 제출의 총 횟수를 제어합니다. 기본값은 **3**(최초 시도 1회 + 재시도 2회)이며, 워크플로 노드별로 설정할 수 있습니다(범위: 1–3).

* **재시도 피드백** — 시도 횟수가 남아 있는 동안 재시도 가능한 실패가 발생하면 사용자는 해당 단계에 머물며 `feedback_codes`가 반환됩니다(웹 및 모바일 SDK는 이를 코칭 메시지로 자동 표시합니다):

  ```json theme={null}
  {
    "detail": "Make sure your face matches your document photo, improve lighting and try again.",
    "error": "LOW_FACE_MATCH_SIMILARITY",
    "feedback_codes": ["LOW_FACE_MATCH_SIMILARITY"],
    "attempts_used": 1,
    "max_attempts": 3
  }
  ```

* **한도 소진** — 시도 횟수가 모두 소진되면 산출된 상태(`Declined` 또는 `In Review`)가 적용됩니다.> [!NOTE]
>
> 재시도는 **세션 플로우**에만 적용됩니다. 독립형 `POST /v3/face-match/` endpoint는 상태 비저장 및 단발성이며, 재시도 한도 없이 유사도 점수를 직접 반환합니다.## 작동 방식**1. 지능형 촬영**직관적인 AI 기반 촬영 시스템으로 인증 절차를 손쉽게 시작할 수 있습니다.사용자는 실시간 안내를 받으며 신분증 문서를 업로드하거나 촬영합니다:| 기능 | 설명 |
| - | - |
| **자동 감지** | 문서 유형과 발급 국가를 자동으로 식별 |
| **실시간 안내** | 최적의 위치, 조명, 초점을 위한 시각적 힌트 제공 |
| **스마트 촬영** | 조건이 완벽할 때 자동 촬영 — 수동 재시도 불필요 |
| **광범위한 지원** | 여권, 운전면허증, 주민등록증/국가 신분증, 거주 허가증 지원 |> [!NOTE]
>
> *중요한 이유*: 지능형 촬영은 사용자의 불편을 줄이고 첫 번째 시도에서 고품질 제출을 보장하여 전환율과 신뢰도를 높입니다.**2. 고급 데이터 처리**탁월한 정밀도로 신원 데이터를 추출하고 검증합니다.**데이터 추출** — 최첨단 기술로 모든 주요 필드를 처리합니다:| 역량 | 세부 정보 |
| - | - |
| **필드 추출** | 성명, 생년월일, 문서 번호, 발급일/만료일, 국적 등 |
| **OCR** | 텍스트를 위한 고정밀 광학 문자 인식 |
| **MRZ 파싱** | 머신 판독 영역 파싱 및 바코드 디코딩 |**데이터 검증**:* 일관성 확인을 위해 시각적 영역, MRZ, 바코드 간의 데이터를 교차 대조
* 이상 징후를 감지하기 위한 형식 및 패턴 매칭
* 공신력 있는 확인을 위한 정부 데이터베이스 실시간 조회(허용된 경우)> [!NOTE]
>
> *중요한 이유*: 종합적인 데이터 처리를 통해 정확도를 보장하고 오류를 제거하여 모든 인증에 대한 확신을 제공합니다.**3. 고급 분석**AI 기반 시스템이 다음과 같은 종합 검사를 수행합니다:- 문서 진위 확인
- 위변조 감지 및 이미지 무결성 분석
- 보안 요소 검증(홀로그램, 워터마크 등)
- 인증된 데이터베이스와의 템플릿 매칭**문서 라이브니스 감지**는 다음과 같은 사기를 방지합니다:| 공격 유형 | 설명 |
| - | - |
| **화면 캡처** | 화면에 표시된 디지털 문서를 촬영한 사진 |
| **화면 재생** | 화면에 표시되는 문서를 촬영한 사진 |
| **인쇄된 사본** | 원본 문서를 물리적으로 복제한 인쇄물 |
| **변조된 인물 사진** | 사진이 교체되거나 편집되어 조작된 문서 |**4. 원활한 결과 및 연동**유연한 전송 옵션을 통해 실행 가능한 인사이트를 즉시 확인할 수 있습니다.**실시간 결과**:| 채널 | 설명 |
| - | - |
| **대시보드** | 직관적인 대시보드를 통한 즉각적인 업데이트 |
| **webhook** | 자동화된 워크플로를 위한 즉각적인 webhook 알림 |
| **REST API** | 기존 시스템과의 원활한 연동 |**종합 보고서**:* 인증 결과와 증거 자료가 포함된 상세 PDF 보고서
* 규정 준수 및 기록 보관을 위한 감사 추적
* 운영 요구 사항에 맞춘 맞춤형 설정 옵션> [!NOTE]
>
> *중요한 이유*: 빠르고 접근하기 쉬운 결과를 통해 안전하고 감사 가능한 프로세스를 유지하면서 팀이 신속하게 조치를 취할 수 있습니다.***## 문서 요구사항최적의 인증 성공률을 위해 문서는 다음 기준을 충족해야 합니다:#### 일반 요구사항- 정부에서 발급하고 설정된 유효 기간 내에 있는 유효한 문서
- 물리적으로 온전한 상태(세부 정보를 가리는 손상, 긁힘, 얼룩이 없음)
- 모든 중요 정보(성명, 생년월일, MRZ 등)가 선명하게 판독 가능해야 함
- 제출된 모든 문서 간의 데이터 일관성 유지#### 이미지 요구사항- 실시간 원본 사진(스크린샷, 스캔본 또는 디지털 사본 불가)
- 지원 형식: JPG, JPEG, PNG, PDF
- 최대 파일 크기: 5MB
- 문서의 모든 모서리가 보이는 풀컬러 이미지
- 빛 반사, 그림자, 디지털 편집 또는 조작이 없어야 함
- 실물 문서 필요(디지털 신분증은 공식적으로 인정되는 특정 지역에서만 지원됨)## 국가 및 문서 유형별 추가 설정콘솔에서 국가 및 문서 유형별로 세부 규칙을 직접 구성할 수 있습니다. 이러한 설정을 통해 컴플라이언스 요구사항에 맞게 수락 기준과 텍스트 변환 환경설정을 맞춤 설정할 수 있습니다.![유사도 임계값 및 수락 규칙을 위한 Didit 얼굴 대조 고급 설정 패널](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/id-additional-settings.jpeg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=4238b10a404795a61926fbdf1a3adc20)* **만료 모드**: 만료일이 지난 문서를 처리하는 방식을 선택합니다.
  * **만료된 문서 거부**: 문서의 만료일이 오늘보다 이전인 경우, 만료된 것으로 표시하고 거부합니다.
  * **만료된 문서 허용**: 만료일이 지난 문서에 플래그를 지정하거나 차단하지 않습니다.
* **선호 문자 형식**: 추출된 성명 및 필드를 정규화할 방식을 선택합니다.
  * **라틴 문자(A–Z) 선호**: 예: "Mohammed"
  * **원래 문자 체계(비라틴 문자) 선호**: 예: "محمد"
* **지역 지원 및 하위 유형**: 지역별로 문서를 활성화하고, 문서 유형에 여러 변형이 포함된 경우 허용 가능한 하위 유형을 지정합니다.
  * 예: 미국 운전면허증의 경우 허용할 정확한 하위 유형을 선택합니다(예: Arizona Commercial Driver License, Indiana Operator License (REAL ID), New York Enhanced Driver License 등).
  * "허용되는 하위 유형" 제어 기능을 사용하여 여러 변형을 빠르게 포함하거나 제외할 수 있습니다(예: "128개 선택됨").> 팁: 이러한 설정은 국가 및 문서 유형별로 적용되므로, 특정 시장에서는 엄격하게 적용하고 다른 시장에서는 보다 유연하게 적용할 수 있습니다.


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