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

# Relatório de estimativa de idade: esquema JSON e campos

> Analise respostas de Estimativa de idade na Didit: idade estimada, prova de vida, limiares e avisos. Pagamento por chamada desde $0.10.

O relatório de Estimativa de idade recolhe uma idade prevista pelo modelo (em anos) para o maior rosto detetado numa imagem, juntamente com uma verificação de prova de vida passiva que confirma que o sujeito é uma pessoa real e não uma fotografia, ecrã ou máscara. As duas verificações são sempre executadas em conjunto — a Estimativa de idade nunca devolve uma idade sem uma pontuação de prova de vida.

Esta página documenta a estrutura JSON devolvida por ambos os métodos de chamada: o endpoint autónomo `POST /v3/age-estimation/` e o campo `age_estimation` integrado nos relatórios de prova de vida do fluxo.

![Relatório de estimativa de idade da Didit com idade prevista, pontuação de prova de vida passiva e métricas de qualidade do rosto](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)

## Visão geral

A Estimativa de idade tem dois modos de disponibilização:

* **API autónoma.** O endpoint `POST /v3/age-estimation/` aceita uma única imagem de rosto (`user_image`) e devolve a idade prevista e a pontuação de prova de vida passiva de forma síncrona. Consulte a [referência da API autónoma de Estimativa de idade](https://docs.didit.me/pt/standalone-apis/age-estimation.md).
* **Integrada num fluxo.** Cada relatório de prova de vida do fluxo inclui a idade prevista sob `age_estimation` — o valor é sempre preenchido a partir do maior rosto detetado. Os limiares de idade só são *aplicados* (acionando avisos de idade) em fluxos de estimativa de idade: fluxos adaptativos de verificação de idade ou nós de fluxo `AGE_ESTIMATION`.

Cada relatório contém:

* O `status` geral (`Approved`, `Declined`).
* O `method` de prova de vida (sempre `PASSIVE` na API autónoma; `ACTIVE_3D` / `FLASHING` / `PASSIVE` em fluxos).
* Uma pontuação (`score`) de prova de vida (0–100; quanto mais alta, maior é a confiança de que o sujeito está vivo; `null` é tratado como `0` para verificações de limiar).
* A `age_estimation` prevista em anos (float — por exemplo `27.33`; `null` quando não foi possível estimar a idade do rosto).
* Apenas na versão autónoma: um objeto `user_image` com uma matriz `entities[]` (uma entrada por rosto detetado — `age`, `bbox`, `confidence`, `gender`) e a orientação `best_angle`.
* Apenas no fluxo: `reference_image`, `video_url`, `matches[]` e as métricas de qualidade de prova de vida passiva `face_quality` (0–100%) e `face_luminance` (0–100%). A resposta autónoma **não** inclui estes campos.
* Uma matriz `warnings[]` — eventos de risco emitidos durante a verificação (consulte [Avisos de Estimativa de idade](https://docs.didit.me/pt/core-technology/age-estimation/warnings-age-estimation.md)).

A decisão na versão autónoma é `Declined` sempre que `warnings` não estiver vazia — `Approved` requer uma matriz vazia. Os avisos são acionados quando:

* O `score` de prova de vida é igual ou inferior a `face_liveness_score_decline_threshold` (predefinição `30`) — `LOW_LIVENESS_SCORE`.
* A idade prevista é inferior a `age_estimation_decline_threshold` (predefinição `18`) — `AGE_BELOW_MINIMUM`. Defina o limiar como `0` para desativar a verificação de idade.
* Nenhum rosto é detetado (`NO_FACE_DETECTED`) ou não foi possível estimar a idade do rosto (`AGE_NOT_DETECTED`).
* O modelo de prova de vida sinaliza um ataque de apresentação (`LIVENESS_FACE_ATTACK`).

## Onde aparece nas respostas da API

### API autónoma — `POST /v3/age-estimation/`

A resposta autónoma encapsula o resultado num único objeto `age_estimation` de nível superior, juntamente com `request_id` e os valores reproduzidos de `vendor_data` / `metadata`. Quando `save_api_request=true` (a predefinição), `request_id` é o ID de sessão persistido e o resultado também pode ser obtido mais tarde a partir do endpoint de decisão; quando `false`, é um UUID de correlação utilizado uma única vez.

```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"
}
```

### Decisão do fluxo — `GET /v3/session/{session_id}/decision/`

Numa sessão de fluxo, a idade prevista está **integrada no relatório de prova de vida — não existe uma matriz separada de estimativa de idade**. O endpoint de decisão V3 devolve os relatórios de prova de vida sob a chave de matriz no plural **`liveness_checks`** (`ReducedSessionV3DecisionSerializer.get_liveness_checks`), e cada entrada inclui um valor de ponto flutuante em `age_estimation` — a idade estimada do maior rosto detetado — ou `null` se nenhuma idade tiver sido calculada (`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,
      "...": "..."
    }
  ]
}
```

Leia a idade a partir de `liveness_checks[].age_estimation`. As chamadas autónomas persistidas (`save_api_request=true`) aparecem da mesma forma no endpoint de decisão, com `features` a conter `AGE_ESTIMATION`.

## Esquema

O esquema canónico campo a campo encontra-se na página [Modelos de dados](https://docs.didit.me/pt/reference/data-models.md#estimativa-de-idade). A estrutura da resposta autónoma é documentada por `AgeEstimationResponseSerializer` e montada em `AgeEstimationAPIView`; o valor do fluxo é produzido por `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[];
}
```

### Valores de estado

As cadeias de caracteres de estado provêm do enum partilhado de estado da funcionalidade (consulte [Enums de estado](https://docs.didit.me/pt/reference/data-models.md#referência-dos-estados)). O endpoint autónomo apenas devolve:

| Estado | Significado |
| - | - |
| `Approved` | Nenhum aviso acionado — o sujeito está vivo e a idade prevista cumpre o limiar configurado. |
| `Declined` | Pelo menos um aviso acionado — pontuação de prova de vida baixa, idade abaixo do limiar, ausência de rosto, ausência de idade ou ataque. |

Nas sessões de fluxo, a verificação de prova de vida também pode ser resolvida como `In Review` quando um risco configurável é acionado com uma ação de revisão (por exemplo, `POSSIBLE_DUPLICATED_FACE`). Consulte a [referência do enum de estado](https://docs.didit.me/pt/reference/data-models.md#referência-dos-estados).

## Exemplos

### Approved — autónomo, sujeito adulto

```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 — autónomo, idade prevista abaixo do limiar

```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 — integrado num relatório de prova de vida de fluxo

```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": []
}
```

## Nota de segurança

Todos os URLs de imagem e vídeo devolvidos na resposta são ligações pré-assinadas com uma janela de validade limitada. Trate-os como referências de curta duração — não os partilhe publicamente e chame novamente o endpoint de decisão para atualizar URLs expirados. Como boa prática, armazene apenas o estado de verificação e os valores de confiança do seu lado, em vez dos dados biométricos subjacentes.

## Relacionado

* [Visão geral da Estimativa de idade](https://docs.didit.me/pt/core-technology/age-estimation/overview.md) — comportamento da funcionalidade, preços, lógica de decisão.
* [Avisos de Estimativa de idade](https://docs.didit.me/pt/core-technology/age-estimation/warnings-age-estimation.md) — todos os códigos de risco e acionadores de recusa.
* [Referência da API autónoma](https://docs.didit.me/pt/standalone-apis/age-estimation.md) — pedido e resposta de `POST /v3/age-estimation/`.
* [Modelos de dados — estimativa de idade](https://docs.didit.me/pt/reference/data-models.md#estimativa-de-idade) — esquema canónico campo a campo.
* [Prova de vida passiva](https://docs.didit.me/pt/core-technology/liveness/overview.md) — o modelo partilhado de prova de vida utilizado nas respostas de estimativa de idade.


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