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

# 年龄估算报告：JSON Schema 与字段解析

> 解析 Didit 年龄估算响应：包含估算年龄、被动活体检测分数、人脸质量指标、拒绝阈值及警告代码。按调用次数计费，低至 $0.10。

年龄估算报告会记录在图像中检测到的最大人脸的模型预测年龄（以岁为单位），并结合无感活体检测，以确认主体是真人而非照片、屏幕或面具。这两项检查始终一同运行 — 年龄估算绝不会在没有活体检测分数的情况下返回年龄。

本页面记录了两种调用路径返回的 JSON 结构：独立的 `POST /v3/age-estimation/` endpoint 以及工作流活体检测报告中内嵌的 `age_estimation` 字段。

![包含预测年龄、无感活体检测分数和人脸质量指标的 Didit 年龄估算报告](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/age-estimation-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=f0ae767c591e55866d0cf5496291e17b)

## 概述

年龄估算有两种交付模式：

* **独立 API。**`POST /v3/age-estimation/` 接收单张人脸图像（`user_image`）并同步返回预测年龄和无感活体检测分数。请参阅[年龄估算独立 API 参考](https://docs.didit.me/zh/standalone-apis/age-estimation.md)。
* **内嵌于工作流。**每个工作流活体检测报告都会在 `age_estimation` 下包含预测年龄 — 该值始终基于检测到的最大人脸生成。年龄阈值仅在年龄估算流程中*强制执行*（触发年龄警告）：即自适应年龄验证工作流或 `AGE_ESTIMATION` 工作流节点。

每份报告包含：

* 总体 `status`（`Approved`、`Declined`）。
* 活体检测 `method`（在独立 API 上始终为 `PASSIVE`；在工作流中为 `ACTIVE_3D` / `FLASHING` / `PASSIVE`）。
* 活体检测 `score`（0–100；分值越高代表主体为真人的置信度越高；进行阈值检查时 `null` 将被视为 `0`）。
* 预测的 `age_estimation`，以岁为单位（浮点数 — 例如 `27.33`；当无法估算人脸年龄时为 `null`）。
* 仅限独立模式：包含 `entities[]` 数组的 `user_image` 对象（每个检测到的人脸对应一项 — 包含 `age`、`bbox`、`confidence`、`gender`）以及 `best_angle` 方向。
* 仅限工作流模式：`reference_image`、`video_url`、`matches[]`，以及无感活体检测质量指标 `face_quality`（0–100%）和 `face_luminance`（0–100%）。独立响应中**不**包含这些字段。
* `warnings[]` 数组 — 检查期间触发的风险事件（请参阅[年龄估算警告](https://docs.didit.me/zh/core-technology/age-estimation/warnings-age-estimation.md)）。

只要 `warnings` 非空，独立决策即为 `Declined` — `Approved` 要求数组为空。以下情况会触发警告：

* 活体检测 `score` 低于或等于 `face_liveness_score_decline_threshold`（默认值为 `30`）— `LOW_LIVENESS_SCORE`。
* 预测年龄低于 `age_estimation_decline_threshold`（默认值为 `18`）— `AGE_BELOW_MINIMUM`。将阈值设置为 `0` 可禁用年龄检查。
* 未检测到人脸（`NO_FACE_DETECTED`）或无法估算人脸年龄（`AGE_NOT_DETECTED`）。
* 活体检测模型标记出呈现攻击（`LIVENESS_FACE_ATTACK`）。

## 在 API 响应中的位置

### 独立 API — `POST /v3/age-estimation/`

独立响应将结果封装在顶层的单个 `age_estimation` 对象中，同时附带 `request_id` 以及原样返回的 `vendor_data` / `metadata`。当 `save_api_request=true`（默认值）时，`request_id` 为持久化的会话 ID，随后也可以从决策 endpoint 获取该结果；当为 `false` 时，它是一个一次性的关联 UUID。

```json theme={null}
{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "age_estimation": {
    "status": "Approved",
    "method": "PASSIVE",
    "score": 97.5,
    "age_estimation": 27.33,
    "user_image": { "entities": [ /* ... */ ], "best_angle": 0 },
    "warnings": []
  },
  "vendor_data": "user-123",
  "metadata": { "flow": "age-gate" },
  "created_at": "2026-06-12T02:24:11.512941+00:00"
}
```

### 工作流决策 — `GET /v3/session/{session_id}/decision/`

在工作流会话中，预测年龄**内嵌在活体检测报告内部 — 不存在单独的年龄估算数组**。V3 决策 endpoint 以复数数组键 **`liveness_checks`**（`ReducedSessionV3DecisionSerializer.get_liveness_checks`）返回活体检测报告，并且每个条目都包含一个 `age_estimation` 浮点数 — 即检测到的最大人脸的估算年龄 — 如果未计算年龄，则为 `null`（`LivenessV2Serializer.get_age_estimation`）。

```json theme={null}
{
  "session_id": "11111111-1111-1111-1111-111111111111",
  "status": "Approved",
  "features": ["AGE_ESTIMATION"],
  "liveness_checks": [
    {
      "node_id": "feature_age_estimation_1",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 89.92,
      "age_estimation": 24.3,
      "...": "..."
    }
  ]
}
```

请从 `liveness_checks[].age_estimation` 中读取年龄。持久化的独立调用（`save_api_request=true`）在决策 endpoint 上以相同的方式呈现，且其 `features` 中包含 `AGE_ESTIMATION`。

## 模式

规范的逐字段模式请参阅[数据模型](https://docs.didit.me/zh/reference/data-models.md#年龄估算)页面。独立响应结构由 `AgeEstimationResponseSerializer` 定义并在 `AgeEstimationAPIView` 中组装；工作流值由 `LivenessV3Serializer` 生成。

```typescript theme={null}
interface AgeEstimationStandalone {
  request_id: string;                  // Session id when save_api_request=true
  age_estimation: {
    status: "Approved" | "Declined";
    method: "PASSIVE";
    score: number | null;              // Passive liveness score (0-100); null counts as 0
    age_estimation: number | null;     // Predicted age in years of the largest face (float)
    user_image: {
      entities: Array<{
        age: number;                   // Estimated age of this face
        bbox: [number, number, number, number];  // [x_min, y_min, x_max, y_max]
        confidence: number;            // Face-detection confidence (0-1)
        gender: "male" | "female";
      }>;
      best_angle: number | null;       // Rotation (0/90/180/270) with best detection
    };
    warnings: Warning[];
  };
  vendor_data: string | null;          // Echoed from the request
  metadata: object | null;             // Echoed from the request
  created_at: string;                  // ISO 8601
}

interface WorkflowLivenessWithAge {
  node_id: string | null;
  status: "Approved" | "Declined" | "In Review";
  method: "ACTIVE_3D" | "FLASHING" | "PASSIVE";
  score: number | null;                // Liveness score (0-100)
  reference_image: string;             // Presigned URL
  video_url: string | null;            // Presigned URL (active liveness only)
  age_estimation: number | null;       // Predicted age in years (float)
  face_quality: number | null;         // 0-100% (passive liveness only)
  face_luminance: number | null;       // 0-100% (passive liveness only)
  warnings: Warning[];
  matches: FaceMatch[];
}
```

### 状态值

状态字符串来自通用的功能状态枚举（请参阅[状态枚举](https://docs.didit.me/zh/reference/data-models.md#状态枚举参考)）。独立 endpoint 仅会返回：

| 状态 | 含义 |
| - | - |
| `Approved` | 未触发任何警告 — 主体为真人且预测年龄符合配置的阈值。 |
| `Declined` | 触发了至少一项警告 — 活体检测分数低、年龄低于阈值、未检测到人脸、无法估算年龄或遭受攻击。 |

在工作流会话中，当可配置的风险触发审核操作（例如 `POSSIBLE_DUPLICATED_FACE`）时，活体检测的结果也可以为 `In Review`。请参阅[状态枚举参考](https://docs.didit.me/zh/reference/data-models.md#状态枚举参考)。

## 示例

### Approved — 独立模式 - 成年主体

```json theme={null}
{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "age_estimation": {
    "status": "Approved",
    "method": "PASSIVE",
    "score": 97.5,
    "age_estimation": 27.33,
    "user_image": {
      "entities": [
        { "age": 27.33, "bbox": [40, 40, 100, 100], "confidence": 0.72, "gender": "male" }
      ],
      "best_angle": 0
    },
    "warnings": []
  },
  "vendor_data": "user-123",
  "metadata": { "flow": "age-gate" },
  "created_at": "2026-06-12T02:24:11.512941+00:00"
}
```

### Declined — 独立模式 - 预测年龄低于阈值

```json theme={null}
{
  "request_id": "b2c3d4e5-f6a7-8901-2345-67890abcdef0",
  "age_estimation": {
    "status": "Declined",
    "method": "PASSIVE",
    "score": 92.0,
    "age_estimation": 15.8,
    "user_image": {
      "entities": [
        { "age": 15.8, "bbox": [55, 60, 110, 110], "confidence": 0.81, "gender": "female" }
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "AGE_BELOW_MINIMUM",
        "feature": "LIVENESS",
        "additional_data": null,
        "log_type": "error",
        "short_description": "Age below minimum",
        "long_description": "The age of the face is below the minimum age threshold for the application."
      }
    ]
  },
  "vendor_data": "user-456",
  "metadata": null,
  "created_at": "2026-06-12T02:26:40.118332+00:00"
}
```

### Approved — 内嵌于工作流活体检测报告

```json theme={null}
{
  "node_id": "feature_age_estimation_1",
  "status": "Approved",
  "method": "PASSIVE",
  "score": 89.92,
  "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
  "video_url": null,
  "age_estimation": 24.3,
  "matches": [],
  "face_quality": 87.5,
  "face_luminance": 54.12,
  "warnings": []
}
```

## 安全说明

响应中返回的所有图像和视频 URL 均为具有有限有效期的预签名链接。请将这些链接视为短期引用 — 请勿公开发布，并在 URL 过期时重新调用决策 endpoint 进行刷新。作为最佳实践，建议您在自身系统中仅存储验证状态和置信度数值，而非底层的生物识别媒体文件。

## 相关内容

* [年龄估算概述](https://docs.didit.me/zh/core-technology/age-estimation/overview.md) — 功能行为、定价、决策逻辑。
* [年龄估算警告](https://docs.didit.me/zh/core-technology/age-estimation/warnings-age-estimation.md) — 所有风险代码和拒绝触发条件。
* [独立 API 参考](https://docs.didit.me/zh/standalone-apis/age-estimation.md) — `POST /v3/age-estimation/` 请求与响应。
* [数据模型 — 年龄估算](https://docs.didit.me/zh/reference/data-models.md#年龄估算) — 规范的逐字段模式。
* [无感活体检测](https://docs.didit.me/zh/core-technology/liveness/overview.md) — 年龄估算响应中使用的通用活体检测模型。


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