> ## 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 通过 AI 人脸分析自拍照核验年龄。每次调用 $0.10，在 16-17 岁区间的平均绝对误差仅 1.1 岁，支持可选的身份证件验证回退。

Didit 年龄估算可通过自拍照预测个人年龄，并包含被动活体检测，因此您无需向每位用户索取身份证件即可对受年龄限制的服务实施准入控制。该模型在年龄准入决策的关键年龄段最为精确：对于 16 至 17 岁人群，其平均绝对误差为 1.1 岁；对于 18 至 20 岁人群，其平均绝对误差为 1.9 岁；并能将 96% 的自拍照正确归类为未满 18 岁或已满 18 岁（请参阅[模型性能](#模型性能与统计数据)）。

年龄估算集成提示词
        将提示词复制到剪贴板



      
      

\<pre>

\````# Goal
Integrate Didit Age Estimation (selfie-based age gating, includes passive liveness) into your app. Pick ONE mode.

\# Mode A — Session-based (embedded in Liveness)
In hosted Didit flows, age estimation is **embedded inside the Liveness step** — there is no separate "age_estimation" workflow feature. Enable age estimation on the Liveness node in the Business Console.

1\. Configure the workflow's LIVENESS feature with age estimation enabled and set age_estimation_decline_threshold (default 18).
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/.

Decision surface: the result lives at `liveness_checks[].age_estimation` on each Liveness entry (not in a top-level age_estimations[] array).

\# Mode B — Standalone API (server-to-server, age + liveness in one call)
Use when you already have a selfie and need a one-shot age gate.

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

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/age-estimation/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'age_estimation_decline_threshold=18' \
-F 'save_api_request=true' \
-F 'vendor_data=user-1234'
\```
Returns: { request_id, age_estimation: { status, method: "PASSIVE", age_estimation (float, years), score (passive-liveness 0-100), user_image: {entities}, warnings: [...] } }.

Required: `user_image` (jpg/jpeg/png/tiff/webp, max 5 MB; PDFs not accepted). The largest face wins when multiple are present.

\# Decision logic
status="Declined" when ANY of the following is true:
\- passive-liveness score ≤ face_liveness_score_decline_threshold (default 30)
\- predicted age < age_estimation_decline_threshold (default 18)
\- no face detected
\- liveness model flagged a presentation attack

\# Status enum
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"

\# Warnings
warnings[] risk codes include:
AGE_BELOW_MINIMUM, AGE_NOT_DETECTED, LOW_LIVENESS_SCORE, NO_FACE_DETECTED, LIVENESS_FACE_ATTACK, MULTIPLE_FACES_DETECTED.
Full catalogue: /core-technology/age-estimation/warnings-age-estimation.

\# Failure modes to handle
\- HTTP 400 — missing or oversized user_image, unsupported extension.
\- HTTP 403 — out of credits.
\- status="Declined" with AGE_BELOW_MINIMUM — user is below the configured age; reject.
\- status="Declined" with LOW_LIVENESS_SCORE / LIVENESS_FACE_ATTACK — presentation attack suspected; reject.
\- AGE_NOT_DETECTED — the model could not extract age (poor image quality); request a retake.

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

\</pre>



      
      

粘贴到

## 年龄估算方法我们的平台结合不同的活体验证技术来实现年龄估算：<table>
  <thead>
    <tr>
      <th>方法</th>
      <th>描述</th>
      <th>安全级别</th>
      <th>最适用场景</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**`3D Action & Flash`**</td>

      <td>
        • 结合多因素生物识别验证与**随机动作序列**以及**动态光照模式分析**。\

        • 开始时，系统会提示用户执行简单动作（例如**眨眼**或**点头**），以确保实时交互。\

        • 与此同时，系统会将一系列光照图案投射到人脸，分析**反光**以确认人脸的三维结构。\

        • **深度学习算法**检查微表情和光线反射响应，以验证真人存在。\

        • 通过整合行为（动作）和物理（基于光线的深度）线索提供**最高安全性**，使得使用静态图像、视频甚至高级面具几乎不可能实施欺骗攻击。
      </td>

      <td>最高</td>
      <td>银行、医疗健康、政府应用</td>
    </tr>

    <tr>
      <td>**`3D Flash`**</td>

      <td>
        • 使用**动态光照模式分析**来验证人脸拓扑结构，无需用户交互。\

        • 以每秒超过 **30 帧**的速度向人脸投射一系列光照图案，分析反光以构建**深度图**。\

        • 该深度图确认人脸的三维结构，将其与平面图像或 2D 欺骗攻击区分开来。\

        • 提供**无缝体验**，同时对照片或屏幕等呈现攻击保持**高安全性**。\

      </td>

      <td>高</td>
      <td>金融服务、账户访问、身份验证</td>
    </tr>

    <tr>
      <td>**`Passive Liveness`**</td>

      <td>
        • 依托**单帧深度学习分析**来检测活体迹象。\

        • 出于隐私保护考虑，用户人脸在界面中显示为模糊状态，让用户放心，其图像仅用于年龄估算，而非身份识别。\

        • 检查图像中的**伪影**、**纹理图案**及其他细微指标，以区分真人面孔与欺骗攻击。\

        • **卷积神经网络（CNN）**验证面部特征并识别异常，例如来自打印照片或数字屏幕的异常。\

        • 提供**快速便捷**的验证，但提供**标准安全性**，适用于低风险场景。\

      </td>

      <td>标准</td>
      <td>低摩擦场景、消费者应用</td>
    </tr>
  </tbody>
</table>每种方法均可生成精确的年龄估算，并附带置信度分数和补充的性别估算数据。### 可配置阈值您可以通过设置不同的年龄估算阈值来自定义安全级别。例如：![用于年龄门控策略的 Didit 年龄估算阈值配置](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/age-estimation-thresholds.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=11ffd7baa63b7193970c6b67386279f8)> [!NOTE]
>
> 这些阈值可以根据您的风险承受能力和安全要求进行调整。### 按国家/地区设置年龄限制年龄限制可以**按国家/地区逐一配置**，以反映不同司法管辖区法定成年年龄的差异。您无需设置单一的全局最低或最高年龄，而是可以为每个国家/地区定义特定的年龄限制，甚至细化到国家内部的各个州或地区。#### 工作原理- **国家/地区级别配置**：为每个国家/地区（通过证件的签发国家/地区识别）设置最低和/或最高年龄。例如，您可以要求美国的最低年龄为 18 岁，韩国为 19 岁，阿拉伯联合酋长国为 21 岁。
- **州/地区覆盖**：对于存在次国家级差异的国家/地区（例如美国或墨西哥），您可以按州配置覆盖规则。例如，密西西比州可能要求最低年龄为 21 岁，而美国默认值为 18 岁。系统使用 OCR 从证件中提取的地区信息来匹配对应的州。
- **法定成年年龄默认值**：控制台提供了一键“应用法定成年年龄”按钮，根据全球已知的法定成年年龄自动填充每个国家/地区的最低年龄。随后，您可以根据需要自定义各个国家/地区或州。
- **可配置操作**：当用户的年龄低于其证件所属国家/地区的最低年龄或超出最高年龄时，您可以选择要执行的操作：**拒绝**或**审核**。#### 示例配置| 国家/地区 | 最低年龄 | 最高年龄 | 州覆盖 |
| - | - | - | - |
| USA | 18 | -- | Mississippi: 21, Alabama: 19 |
| KOR | 19 | -- | -- |
| GBR | 18 | 65 | -- |
| ARE | 21 | -- | -- |> [!NOTE]
>
> 按国家/地区设置年龄限制在标准 KYC 工作流和自适应年龄验证工作流中均可使用。在自适应工作流中，当针对临界情况触发身份证件验证时，年龄核验将使用在身份证件验证步骤中配置的按国家/地区设置。## 工作原理**1. 图像或视频采集**用户通过 API 上传清晰的面部图像，或完成活体核验流程。| 检查项 | 描述 |
| - | - |
| **图像质量** | 验证光照、位置和清晰度 |
| **活体核验** | 确保主体真实在场且未使用欺骗手段 |
| **多帧分析** | 选择最佳帧以实现最高准确率 |
| **自适应采集** | 适应各种设备的能力 |**2. 面部特征分析**检测器会定位图像中的所有人脸和所有人，并对其中最大的人脸进行分析。- **人脸裁剪**：精准检测出的人脸区域，用于分析面部形态、比例和皮肤纹理
- **身体上下文**：遮蔽人脸后的图像其余部分，用于优化估算
- 检测并报告单张图像中的多张人脸，以便对会话进行相应处理**3. 神经网络处理**两个互补的深度神经网络分别独立估算年龄，最终的估算结果取其平均值。- Transformer 会同时读取人脸和身体裁剪区域；卷积网络则读取人脸
- 每个网络均运行 5 个在不同数据子集上训练的模型并取其估算均值，从而使结果更加稳定
- 训练所用年龄均通过身份证件确认，充分涵盖了青少年、年轻成年人以及各种肤色群体
- 仅使用自拍照进行评估，且参与者均为模型训练期间未见过的人**4. 决策与补充分析**系统生成综合结果：| 输出 | 描述 |
| - | - |
| **年龄估算** | 包含置信度评分的主要估算值 |
| **性别估算** | 补充的人口统计学背景信息（可选） |
| **置信度指标** | 整体可靠性评估 |
| **环境因素** | 对估算质量的影响评估 |**5. 规则应用**系统会将您配置的业务规则应用于估算结果。- 年龄估算值会与您**配置的阈值**（每个国家/地区的最低/最高值）进行比对
- 根据您的最低要求检查置信度分数
- **临界情况**可触发回退至身份证件验证（自适应模式）
- 结果会记录在详细的**审计日志**中，以满足合规要求## 自适应年龄估算对于精确年龄验证至关重要的场景，我们的平台提供带有身份证件验证回退机制的自适应年龄估算。这种方法在用户便利性与监管合规之间实现了平衡。### 自适应年龄估算的工作原理**1. 初始年龄估算**系统首先尝试通过人脸分析来估算用户的年龄。在生成年龄估算结果的同时，还会生成置信度分数。**2. 阈值评估**将估算出的年龄与您配置的阈值进行比对。共有三种结果：| 结果 | 描述 |
| - | - |
| **明确通过** | 用户明显高于您要求的年龄阈值 |
| **明确未通过** | 用户明显低于您要求的年龄阈值 |
| **临界** | 估算年龄处于不确定区间内，或置信度较低 |**3. 智能回退**- **明确通过/未通过**：验证立即完成并返回相应结果
- **临界情况**：系统自动发起**身份证件验证流程**
- 这样既能确保监管合规，又能最大程度减少对绝大多数用户的干扰**4. 证件验证（必要时）**对于临界情况，用户需提供政府签发的身份证件：- 核验证件真伪及年龄信息
- 应用身份证件验证步骤中的**各国年龄限制**
- 系统根据证件签发国家/地区及区域的最低/最高年龄要求核对出生日期
- 证件头像会**与之前为年龄估算捕获的自拍照进行 1:1 人脸比对**，从而将证件上的出生日期与摄像头前的人员进行绑定### 回退机制返回的内容回退人脸比对在工作流中无需配置人脸比对节点即可运行，因此它在会话决策中的显示方式很容易让人误以为是一项您从未配置过的检查：- 一旦运行了回退机制，`features` 除了列出 `AGE_ESTIMATION` 和 `ID_VERIFICATION` 之外，还会列出 `FACE_MATCH`。
- `face_matches[]` 包含一项记录，其中带有 `score`、`source_image`（证件头像）和 `target_image`（年龄估算自拍照）。其 `node_id` 为**年龄估算节点**（在原生工作流中为 `feature_age_estimation`），因为该比对属于该步骤，而非独立的人脸比对步骤。
- 分数偏低会触发常规的[人脸比对警告](https://docs.didit.me/zh/core-technology/face-match/warnings-face-match.md)，并可能使该会话进入审核状态或被拒绝，这与配置了人脸比对节点时的行为完全一致。
- 它**不作为**人脸比对计费：该会话仅针对年龄估算和身份证件验证收费。仅凭自拍照即通过或未通过的会话绝不会运行回退机制，因此它们会返回 `face_matches: null`。为了避免在决策 payload 中包含这些图像，可以通过工作流的[响应属性](https://docs.didit.me/zh/sessions-api/retrieve-session.md)来限制 `face_matches` 字段。> [!NOTE]
>
> 自适应年龄估算可以通过 [Adaptive Age Verification](https://docs.didit.me/zh/console/workflows.md) 工作流类型进行配置。您可以定义用于决定何时触发身份证件验证的临界年龄阈值。对于临界情况，最终基于年龄的通过或拒绝决策则由身份证件验证步骤中配置的各国年龄限制所决定。### 自适应年龄估算的优势- **减少摩擦**：绝大多数用户仅需一张自拍照即可完成验证
- **增强合规性**：不确定的情况将根据特定国家/地区的年龄规则进行全面的证件验证
- **成本效益**：仅在必要时才使用身份证件验证
- **可自定义风险承受能力**：根据您的监管要求调整阈值
- **考虑管辖区差异**：根据用户证件签发国家/地区及区域自动应用正确的法定成年年龄这种方法对于有年龄限制的服务（如在线游戏、酒类配送和成人内容平台）尤为宝贵，在这些场景中，平衡用户体验与监管合规至关重要。## 年龄保证 (ISO/IEC 27566-1)工作流可以声明其遵循 ISO/IEC 27566-1 年龄保证标准。
您可以从控制台模板**年龄估计（ISO/IEC 27566-1）**或**年龄验证（ISO/IEC 27566-1）**创建该工作流。
此声明在创建工作流时完成，之后无法更改。当工作流声明遵循该标准时，Didit 会将其固定为针对年龄的一次性“是”或“否”答复。
这些固定的设置适用于控制台中以及通过 API 进行的每一次保存：- **您仅会收到年龄决策，无其他任何内容。** 响应属性已被锁定，因此决策不包含任何个人数据。
- 在每个国家/地区、每个区域覆盖设置以及自适应年龄估算阈值中，**13 岁是允许设置的最低年龄**。低于该值的设置将被拒绝。
- **跨会话不进行识别。** 重复证件与重复人脸检查均处于关闭状态，且不会存储任何生物特征模板。
- **受限采集。** 证件仅可通过摄像头采集，不支持文件上传，拍摄证件时不会静默采集自拍照，也不会录制音频。
- **无额外数据核对。** 预期信息比对和数据复核步骤均处于关闭状态，且身份证件验证仅读取证件，不进行数据库查询，也不使用数字身份钱包。
- **必须设置阈值。** 未设置年龄阈值的工作流在保存时将被拒绝，因此它绝不会默认批准所有人。## 模型性能与统计数据下方数据反映了自 2026 年 11 月 4 日起在生产环境中运行的年龄模型。
这些数据来源于其锁定的评估数据集：包含 2,399 张 13 岁及以上人员的自拍照。该数据集在训练前已被独立留存，且每个人的真实年龄均取自其已验证的身份证件。
没有任何模型使用过这些自拍照或这些人员的数据进行训练。
总体数据基于 10% 18 岁以下人群的评估样本组合，其中成年人符合线上实际流量的年龄分布；下方单独列出了各个年龄段的具体表现。### 准确率指标<table>
  <thead>
    <tr>
      <th>指标</th>
      <th>数值</th>
      <th>描述</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**平均绝对误差 (MAE)**</td>
      <td>2.6 岁</td>
      <td>估算年龄与证件年龄之间的平均差异</td>
    </tr>

    <tr>
      <td>**标准差**</td>
      <td>2.3 岁</td>
      <td>不同估算之间误差的波动程度</td>
    </tr>

    <tr>
      <td>**以 18 岁为阈值的准确率**</td>
      <td>96.0%</td>
      <td>在不设回退区间的情况下，自拍照被正确分类为 18 岁以下或 18 岁及以上的比例；在 95% 置信度下至少达到 95.3%</td>
    </tr>
  </tbody>
</table>### 各年龄段表现在年龄门槛判定所涉及的年龄附近误差最小，并随着年龄增长而增大。<table>
  <thead>
    <tr>
      <th>年龄段</th>
      <th>MAE（岁）</th>
      <th>标准差（岁）</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>13-15</td>
      <td>1.70</td>
      <td>1.17</td>
    </tr>

    <tr>
      <td>16-17</td>
      <td>1.14</td>
      <td>1.37</td>
    </tr>

    <tr>
      <td>18-20</td>
      <td>1.86</td>
      <td>1.74</td>
    </tr>

    <tr>
      <td>21-25</td>
      <td>2.21</td>
      <td>1.78</td>
    </tr>

    <tr>
      <td>26-40</td>
      <td>2.77</td>
      <td>2.20</td>
    </tr>

    <tr>
      <td>41-60</td>
      <td>3.03</td>
      <td>2.62</td>
    </tr>

    <tr>
      <td>60 岁以上</td>
      <td>4.33</td>
      <td>3.64</td>
    </tr>
  </tbody>
</table>> [!NOTE]
>
> 标准差描述的是单次估算误差的离散程度，而非平均值的不确定性。
> 接近您设定的最低年龄 1 到 2 岁的估算结果可能会落在阈值的任一侧：如果在阈值附近的误判至关重要，请将该临界区间分流至[自适应身份证件验证回退流程](#自适应年龄估算)。


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