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

O relatório de Estimativa de idade registra a idade prevista por um modelo (em anos) para o maior rosto detectado em uma imagem, combinada com uma verificação de prova de vida passiva que confirma que a pessoa é real, e não uma foto, uma tela ou uma máscara. As duas verificações sempre são executadas juntas: a Estimativa de idade nunca retorna uma idade sem uma pontuação de prova de vida. Esta página documenta o formato JSON retornado pelas duas formas de chamada: o endpoint independente POST /v3/age-estimation/ e o campo age_estimation incorporado nos relatórios de prova de vida do fluxo de verificação (workflow).

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

Visão geral

A Estimativa de idade tem dois modos de entrega:

API independente. POST /v3/age-estimation/ aceita uma única imagem de rosto (user_image) e retorna a idade prevista e a pontuação de prova de vida passiva de forma síncrona. Consulte a referência da API independente de Estimativa de idade.
Incorporada em um fluxo. Todo relatório de prova de vida de um fluxo traz a idade prevista em age_estimation, e o valor é sempre preenchido a partir do maior rosto detectado. Os limiares de idade só são aplicados (gerando avisos de idade) em fluxos de estimativa de idade: fluxos de verificação de idade adaptativa ou nós AGE_ESTIMATION do fluxo.

Cada relatório contém:

O status geral (Approved, Declined).
O method de prova de vida (sempre PASSIVE na API independente; ACTIVE_3D / FLASHING / PASSIVE em fluxos).
Uma score de prova de vida (0–100; quanto maior, maior a confiança de que a pessoa está viva; null é tratado como 0 nas 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 de nenhum rosto).
Somente na API independente: um objeto user_image com um array entities[] (uma entrada por rosto detectado: age, bbox, confidence, gender) e a orientação best_angle.
Somente em fluxos: reference_image, video_url, matches[] e as métricas de qualidade da prova de vida passiva face_quality (0–100%) e face_luminance (0–100%). A resposta da API independente não inclui esses campos.
Um array warnings[] com os eventos de risco emitidos durante a verificação (consulte Avisos da Estimativa de idade).

Na API independente, a decisão é Declined sempre que warnings não estiver vazio; Approved exige um array vazio. Os avisos são gerados quando:

A score de prova de vida é igual ou inferior a face_liveness_score_decline_threshold (padrão 30): LOW_LIVENESS_SCORE.
A idade prevista é inferior a age_estimation_decline_threshold (padrão 18): AGE_BELOW_MINIMUM. Defina o limiar como 0 para desativar a verificação de idade.
Nenhum rosto é detectado (NO_FACE_DETECTED) ou não foi possível estimar a idade de nenhum 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 independente: `POST /v3/age-estimation/`

A resposta da API independente agrupa o resultado em um único objeto age_estimation de nível superior, junto com request_id e os campos vendor_data / metadata devolvidos tal como foram enviados. Quando save_api_request=true (o padrão), request_id é o ID da sessão persistida e o resultado também pode ser obtido depois pelo endpoint de decisão; quando false, é um UUID de correlação de uso único.

{
  "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/`

Em uma sessão de fluxo, a idade prevista fica incorporada no relatório de prova de vida: não existe um array separado de estimativa de idade. O endpoint de decisão V3 retorna os relatórios de prova de vida na chave de array no plural liveness_checks (ReducedSessionV3DecisionSerializer.get_liveness_checks), e cada entrada traz um age_estimation do tipo float, que é a idade estimada do maior rosto detectado, ou null se nenhuma idade foi calculada (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,
      "...": "..."
    }
  ]
}

Leia a idade em liveness_checks[].age_estimation. As chamadas independentes persistidas (save_api_request=true) aparecem da mesma forma no endpoint de decisão, com features contendo AGE_ESTIMATION.

Esquema

O esquema canônico, campo a campo, está na página Modelos de dados. O formato da resposta da API independente é documentado por AgeEstimationResponseSerializer e montado em AgeEstimationAPIView; o valor do fluxo é produzido por 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[];
}

Valores de status

As strings de status vêm do enum compartilhado de status de recursos (consulte Enums de status). O endpoint independente só retorna:

Status	Significado
`Approved`	Nenhum aviso foi gerado: a pessoa passou na prova de vida e a idade prevista atende ao limiar configurado.
`Declined`	Pelo menos um aviso foi gerado: pontuação de prova de vida baixa, idade abaixo do limiar, nenhum rosto, nenhuma idade ou ataque.

Em sessões de fluxo, a verificação de prova de vida também pode resultar em In Review quando um risco configurável é acionado com uma ação de revisão (por exemplo POSSIBLE_DUPLICATED_FACE). Consulte a referência de enums de status.

Exemplos

Aprovado: independente, pessoa adulta

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

Recusado: API independente, idade prevista abaixo do limiar

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

Aprovado: incorporado em um relatório de prova de vida de um fluxo de trabalho

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

Todas as URLs de imagens e vídeos retornadas na resposta são links pré-assinados com um período de validade limitado. Trate-as como referências de curta duração: não as compartilhe publicamente e chame novamente o endpoint de decisão para renovar URLs expiradas. Como boa prática, armazene do seu lado apenas o status da verificação e os valores de confiança, e não a mídia biométrica em si.

Relacionados

Visão geral da Estimativa de idade: comportamento do recurso, preços e lógica de decisão.
Avisos da Estimativa de idade: todos os códigos de risco e gatilhos de recusa.
Referência da API independente: requisição e resposta de POST /v3/age-estimation/.
Modelos de dados: estimativa de idade: esquema canônico campo a campo.
Prova de vida passiva: o modelo de prova de vida compartilhado usado nas respostas de estimativa de idade.

Autenticação

Verificação

Monitoramento

Plataforma

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

Visão geral

Onde aparece nas respostas da API

API independente: `POST /v3/age-estimation/`

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

Esquema

Valores de status

Exemplos

Aprovado: independente, pessoa adulta

Recusado: API independente, idade prevista abaixo do limiar

Aprovado: incorporado em um relatório de prova de vida de um fluxo de trabalho

Nota de segurança

Relacionados

​Visão geral

​Onde aparece nas respostas da API

​API independente: POST /v3/age-estimation/

​Decisão do fluxo: GET /v3/session/{session_id}/decision/

​Esquema

​Valores de status

​Exemplos

​Aprovado: independente, pessoa adulta

​Recusado: API independente, idade prevista abaixo do limiar

​Aprovado: incorporado em um relatório de prova de vida de um fluxo de trabalho

​Nota de segurança

​Relacionados

Visão geral

Onde aparece nas respostas da API

API independente: `POST /v3/age-estimation/`

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

Esquema

Valores de status

Exemplos

Aprovado: independente, pessoa adulta

Recusado: API independente, idade prevista abaixo do limiar

Aprovado: incorporado em um relatório de prova de vida de um fluxo de trabalho

Nota de segurança

Relacionados