> ## 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–3）。
* **重试反馈** — 在仍有尝试次数时，可重试的失败将使用户停留在活体检测步骤，并返回包含可操作 `feedback_codes` 的响应体（Web 和移动端 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/` endpoint 是无状态且仅支持单次调用的 — 它直接返回结果，没有重试配额。## 工作原理**1. 视频自拍采集**系统通过针对所选活体检测方法定制的**简单、直观的界面**引导用户完成操作。| 检查项目 | 描述 |
| - | - |
| **实时反馈** | 确保合适的光线、位置和取景 |
| **质量检查** | 监测模糊和反光，并确保面部清晰可见 |
| **自适应采集** | 适配各种设备性能和网络状况 |
| **方法指引** | 显示特定方法的说明（例如 3D Action 的“请眨眼”） |**2. 活体检测分析**先进算法**实时**处理采集到的媒体，以检测欺骗攻击。不同方法的分析方式有所不同：> [accordion] 3D Action & Flash
>
> * 验证用户的动作（例如**眨眼**或**点头**），以确认动作执行正确且为真人实时操作
> * 分析**光照图案反射**以验证人脸的三维结构
> * 利用深度学习评估**微表情**及其他行为线索
> * 结合行为与物理信号，实现**最强的防欺骗性能**> [accordion] 3D Flash
>
> * 以 30+ FPS 的帧率处理一系列**光照图案反射**，构建详细的**深度图**
> * 确认人脸的 3D 特征，将其与平面或 2D 欺骗区分开来
> * 无需用户交互 — **从用户角度来看完全是被动的**> [accordion] Passive Liveness
>
> * 对单帧图像应用**深度学习**，检测**纹理图案**和**伪影**
> * 卷积神经网络（CNN）验证面部特征并识别异常
> * 最快的方法 — 仅需**单张照片采集**即可运行多层检测可识别包括照片、屏幕、面具和深度伪造在内的**呈现攻击**。**3. 结果处理与核验**系统将活体检测分数与您**配置的阈值**进行比对，并立即返回结果。| 输出 | 描述 |
| - | - |
| **活体检测分数** | 归一化的 0–100% 置信度分数 |
| **决策** | 根据您的阈值判定为已通过、已拒绝或审核中 |
| **方法** | 使用了哪种活体检测方法（`passive`、`flash`、`action_flash`） |
| **参考图像** | 用于活体检测的采集帧 |
| **警告** | 检测到的任何异常（例如低质量、潜在欺骗指标） |结果通过 **API 响应**、**Webhook** 交付，或可在**业务控制台**中查看，并附带用于合规的详细审计日志。> [!TIP]
>
> 您可以在[业务控制台](https://docs.didit.me/zh/console/workflows.md)中按工作流配置要使用的活体检测方法。不同的工作流可以根据您的风险要求使用不同的方法。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.