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

年龄估算报告会记录在图像中检测到的最大人脸的模型预测年龄（以岁为单位），并结合无感活体检测，以确认主体是真人而非照片、屏幕或面具。这两项检查始终一同运行 — 年龄估算绝不会在没有活体检测分数的情况下返回年龄。本页面记录了两种调用路径返回的 JSON 结构：独立的 POST /v3/age-estimation/ endpoint 以及工作流活体检测报告中内嵌的 age_estimation 字段。

概述

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

独立 API。POST /v3/age-estimation/ 接收单张人脸图像（user_image）并同步返回预测年龄和无感活体检测分数。请参阅年龄估算独立 API 参考。
内嵌于工作流。每个工作流活体检测报告都会在 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[] 数组 — 检查期间触发的风险事件（请参阅年龄估算警告）。

只要 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。

{
  "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）。

{
  "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。

模式

规范的逐字段模式请参阅数据模型页面。独立响应结构由 AgeEstimationResponseSerializer 定义并在 AgeEstimationAPIView 中组装；工作流值由 LivenessV3Serializer 生成。

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[];
}

状态值

状态字符串来自通用的功能状态枚举（请参阅状态枚举）。独立 endpoint 仅会返回：

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

在工作流会话中，当可配置的风险触发审核操作（例如 POSSIBLE_DUPLICATED_FACE）时，活体检测的结果也可以为 In Review。请参阅状态枚举参考。

示例

Approved — 独立模式 - 成年主体

{
  "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 — 独立模式 - 预测年龄低于阈值

{
  "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 — 内嵌于工作流活体检测报告

{
  "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 进行刷新。作为最佳实践，建议您在自身系统中仅存储验证状态和置信度数值，而非底层的生物识别媒体文件。

身份认证

验证

监控

平台

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

概述

在 API 响应中的位置

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

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

模式

状态值

示例

Approved — 独立模式 - 成年主体

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

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

安全说明

相关内容

​概述

​在 API 响应中的位置

​独立 API — POST /v3/age-estimation/

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

​模式

​状态值

​示例

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

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

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

​安全说明

​相关内容

概述

在 API 响应中的位置

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

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

模式

状态值

示例

Approved — 独立模式 - 成年主体

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

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

安全说明

相关内容