> ## 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 免费额度，2 秒内返回匹配分数，助力 KYC 与用户入驻。

Didit Face Match 会对两张人脸进行 1:1 比对（通常是活体检测中的自拍照与用户身份证件上的头像），并返回 0 到 100 之间的相似度分数。您设置的阈值决定了该检查是否通过；独立的 `POST /v3/face-match/` API 默认拒绝 30 分或更低的分数。在关于解读验证结果的学院课程中，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/zh/core-technology/liveness/overview.md)相同。* **尝试次数预算** — `face_match_max_attempts` 控制每次会话的人脸比对提交总次数。默认为 **3** 次（一次初始尝试加两次重试），可在每个工作流节点中配置（范围 1–3）。

* **重试反馈** — 在剩余尝试次数内，可重试的失败会让用户停留在该步骤并返回 `feedback_codes`（Web 和 Mobile 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.