> ## 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-схема и поля

> Ответы Оценки возраста Didit: расчётный возраст, скоринг живости, метрики качества лица, пороги отклонения и предупреждения. От $0.10 за вызов.

Отчёт об оценке возраста содержит определённый моделью возраст (в годах) для самого крупного лица, обнаруженного на изображении, в сочетании с пассивной проверкой живости, подтверждающей, что перед камерой реальный человек, а не фотография, экран или маска. Обе проверки всегда выполняются вместе — Оценка возраста никогда не возвращает возраст без оценки живости.

На этой странице описана структура JSON, возвращаемая обоими путями вызова: отдельным endpoint `POST /v3/age-estimation/` и встроенным полем `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/ru/standalone-apis/age-estimation.md).
* **Встроенный в сценарий.** Каждый отчёт о проверке живости в сценарии содержит предполагаемый возраст в поле `age_estimation` — значение всегда заполняется на основе самого крупного обнаруженного лица. Пороги возраста *применяются* (вызывая возрастные предупреждения) только в сценариях с оценкой возраста: адаптивных сценариях верификации возраста или узлах сценария `AGE_ESTIMATION`.

Каждый отчёт содержит:

* Общий статус `status` (`Approved`, `Declined`).
* Метод проверки живости `method` (всегда `PASSIVE` в отдельном API; `ACTIVE_3D` / `FLASHING` / `PASSIVE` в сценариях).
* Оценку живости `score` (0–100; чем выше, тем выше уверенность в том, что человек жив; `null` обрабатывается как `0` при проверках порогов).
* Предполагаемую оценку возраста `age_estimation` в годах (число с плавающей точкой — например, `27.33`; `null`, если возраст лица не удалось определить).
* Только для отдельного API: объект `user_image` с массивом `entities[]` (по одной записи для каждого обнаруженного лица — `age`, `bbox`, `confidence`, `gender`) и ориентацией `best_angle`.
* Только для сценариев: `reference_image`, `video_url`, `matches[]` и метрики качества пассивной проверки живости `face_quality` (0–100%) и `face_luminance` (0–100%). Ответ отдельного API **не** включает эти поля.
* Массив `warnings[]` — события риска, зафиксированные во время проверки (см. [предупреждения Оценки возраста](https://docs.didit.me/ru/core-technology/age-estimation/warnings-age-estimation.md)).

В отдельном API принимается решение `Declined` всякий раз, когда массив `warnings` не пуст — для `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/`

Ответ отдельного API оборачивает результат в один объект верхнего уровня `age_estimation`, наряду с `request_id` и переданными обратно `vendor_data` / `metadata`. При `save_api_request=true` (по умолчанию) `request_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/`

В сессии сценария предполагаемый возраст **встроен внутрь отчёта о проверке живости — отдельного массива оценки возраста нет**. Endpoint решения V3 возвращает отчёты о проверке живости под ключом массива во множественном числе **`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`. Сохранённые вызовы отдельного API (`save_api_request=true`) отображаются в endpoint решения аналогичным образом, при этом `features` содержит `AGE_ESTIMATION`.

## Схема

Каноническая схема с описанием каждого поля находится на странице [Модели данных](https://docs.didit.me/ru/reference/data-models.md#оценка-возраста). Формат ответа отдельного API задокументирован в `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/ru/reference/data-models.md#справочник-значений-перечисления-status)). Endpoint отдельного API возвращает только:

| Статус | Значение |
| - | - |
| `Approved` | Предупреждения не сработали — человек жив, а предполагаемый возраст соответствует установленному порогу. |
| `Declined` | Сработало как минимум одно предупреждение — низкая оценка живости, возраст ниже порога, лицо не обнаружено, возраст не определён или атака. |

В сессиях сценария проверка живости также может перейти в статус `In Review`, если настраиваемый риск срабатывает с действием отправки на проверку (например, `POSSIBLE_DUPLICATED_FACE`). См. [справочник перечислений статусов](https://docs.didit.me/ru/reference/data-models.md#справочник-значений-перечисления-status).

## Примеры

### Approved — отдельный API, совершеннолетний субъект

```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 — отдельный API, предполагаемый возраст ниже порога

```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-адреса изображений и видео, возвращаемые в ответе, представляют собой предварительно подписанные ссылки с ограниченным сроком действия. Относитесь к ним как к краткосрочным ссылкам — не делитесь ими публично и повторно вызывайте endpoint решения, чтобы обновить ссылки с истёкшим сроком действия. В соответствии с передовыми практиками рекомендуется сохранять на своей стороне только статус верификации и значения уверенности, а не сами исходные биометрические медиафайлы.

## Связанные разделы

* [Обзор Оценки возраста](https://docs.didit.me/ru/core-technology/age-estimation/overview.md) — работа функции, цены, логика принятия решений.
* [Предупреждения Оценки возраста](https://docs.didit.me/ru/core-technology/age-estimation/warnings-age-estimation.md) — все коды рисков и триггеры отклонения.
* [Справочник отдельного API](https://docs.didit.me/ru/standalone-apis/age-estimation.md) — запрос и ответ `POST /v3/age-estimation/`.
* [Модели данных — оценка возраста](https://docs.didit.me/ru/reference/data-models.md#оценка-возраста) — каноническая схема полей.
* [Пассивная проверка живости](https://docs.didit.me/ru/core-technology/liveness/overview.md) — общая модель проверки живости, используемая в ответах оценки возраста.


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