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

# API de estimativa de idade por selfie

> A Didit estima a idade por selfie com IA facial. $0.10 por chamada, erro médio absoluto de 1.0 ano entre 13 e 17 anos e alternativa opcional com documento.

A estimativa de idade da Didit prevê a idade de uma pessoa a partir de uma selfie, com prova de vida passiva incluída, para que você restrinja serviços por idade sem pedir um documento de identidade a todos os usuários. O modelo é mais preciso justamente onde a restrição por idade decide: seu erro médio absoluto é de 1.0 ano para pessoas de 13 a 17 anos e de 1.8 ano para pessoas de 18 a 20 anos (veja [Desempenho do modelo](#desempenho-do-modelo-e-estatísticas)).

Prompt de integração da estimativa de idade
        Copy prompt to clipboard



      
      

\<pre>

\````# Goal
Integrate Didit Age Estimation (selfie-based age gating, includes passive liveness) into your app. Pick ONE mode.

\# Mode A — Session-based (embedded in Liveness)
In hosted Didit flows, age estimation is **embedded inside the Liveness step** — there is no separate "age_estimation" workflow feature. Enable age estimation on the Liveness node in the Business Console.

1\. Configure the workflow's LIVENESS feature with age estimation enabled and set age_estimation_decline_threshold (default 18).
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open session.url for the user (or mount the Web/Mobile SDK).
4\. Fetch the decision — GET /v3/session/{sessionId}/decision/.

Decision surface: the result lives at `liveness_checks[].age_estimation` on each Liveness entry (not in a top-level age_estimations[] array).

\# Mode B — Standalone API (server-to-server, age + liveness in one call)
Use when you already have a selfie and need a one-shot age gate.

POST https://verification.didit.me/v3/age-estimation/
multipart/form-data — x-api-key: YOUR_API_KEY

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/age-estimation/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'age_estimation_decline_threshold=18' \
-F 'save_api_request=true' \
-F 'vendor_data=user-1234'
\```
Returns: { request_id, age_estimation: { status, method: "PASSIVE", age_estimation (float, years), score (passive-liveness 0-100), user_image: {entities}, warnings: [...] } }.

Required: `user_image` (jpg/jpeg/png/tiff/webp, max 5 MB; PDFs not accepted). The largest face wins when multiple are present.

\# Decision logic
status="Declined" when ANY of the following is true:
\- passive-liveness score ≤ face_liveness_score_decline_threshold (default 30)
\- predicted age < age_estimation_decline_threshold (default 18)
\- no face detected
\- liveness model flagged a presentation attack

\# Status enum
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"

\# Warnings
warnings[] risk codes include:
AGE_BELOW_MINIMUM, AGE_NOT_DETECTED, LOW_LIVENESS_SCORE, NO_FACE_DETECTED, LIVENESS_FACE_ATTACK, MULTIPLE_FACES_DETECTED.
Full catalogue: /core-technology/age-estimation/warnings-age-estimation.

\# Failure modes to handle
\- HTTP 400 — missing or oversized user_image, unsupported extension.
\- HTTP 403 — out of credits.
\- status="Declined" with AGE_BELOW_MINIMUM — user is below the configured age; reject.
\- status="Declined" with LOW_LIVENESS_SCORE / LIVENESS_FACE_ATTACK — presentation attack suspected; reject.
\- AGE_NOT_DETECTED — the model could not extract age (poor image quality); request a retake.

\# See also
\- Canonical schema: /reference/data-models#age-estimation
\- Per-feature report: /core-technology/age-estimation/report-age-estimation
\- Risk catalogue: /core-technology/age-estimation/warnings-age-estimation
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

Paste into

## Métodos de estimativa de idadeNossa plataforma implementa a estimativa de idade em conjunto com diferentes tecnologias de verificação de prova de vida:<table>
  <thead>
    <tr>
      <th>Método</th>
      <th>Descrição</th>
      <th>Nível de segurança</th>
      <th>Ideal para</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**`3D Action & Flash`**</td>

      <td>
        • Combina verificação biométrica multifator com uma **sequência de ações aleatória** e **análise dinâmica de padrões de luz**.\

        • No início, o usuário é solicitado a executar uma ação simples - como **piscar** ou **acenar com a cabeça** - garantindo interação em tempo real.\

        • Ao mesmo tempo, o sistema projeta uma sequência de padrões de luz sobre o rosto e analisa os **reflexos** para confirmar a estrutura tridimensional do rosto.\

        • **Algoritmos de deep learning** examinam microexpressões e as respostas aos reflexos de luz para verificar a presença de uma pessoa viva.\

        • Oferece a **máxima segurança** ao integrar sinais comportamentais (ação) e físicos (profundidade por luz), o que torna quase impossível falsificá-la com imagens estáticas, vídeos ou até máscaras avançadas.
      </td>

      <td>Máximo</td>
      <td>Bancos, saúde, aplicações governamentais</td>
    </tr>

    <tr>
      <td>**`3D Flash`**</td>

      <td>
        • Usa **análise dinâmica de padrões de luz** para validar a topologia facial sem exigir interação do usuário.\

        • Projeta uma série de padrões de luz sobre o rosto a mais de **30 quadros por segundo** e analisa os reflexos para criar um **mapa de profundidade**.\

        • Esse mapa de profundidade confirma a estrutura tridimensional do rosto e o distingue de imagens planas ou falsificações 2D.\

        • Oferece uma **experiência fluida**, mantendo **alta segurança** contra ataques de apresentação como fotos ou telas.\

      </td>

      <td>Alto</td>
      <td>Serviços financeiros, acesso a contas, verificação de identidade</td>
    </tr>

    <tr>
      <td>**`Passive Liveness`**</td>

      <td>
        • Baseia-se em **análise de deep learning de um único quadro** para detectar sinais de vida.\

        • Por privacidade, o rosto do usuário aparece desfocado na interface, o que garante que a imagem está sendo analisada apenas para estimar a idade, e não para identificação.\

        • Examina a imagem em busca de **artefatos**, **padrões de textura** e outros indícios sutis que diferenciam um rosto real de uma falsificação.\

        • Uma **rede neural convolucional (CNN)** valida as características faciais e identifica anomalias, como as de fotos impressas ou telas digitais.\

        • Oferece uma verificação **rápida e conveniente**, mas com **segurança padrão**, adequada a casos de uso de baixo risco.\

      </td>

      <td>Padrão</td>
      <td>Cenários de baixo atrito, aplicações para o consumidor</td>
    </tr>
  </tbody>
</table>Cada método gera uma estimativa de idade precisa, junto com pontuações de confiança e dados complementares de estimativa de gênero.### Limites configuráveisVocê pode personalizar os níveis de segurança definindo limites diferentes para a estimativa de idade. Por exemplo:![Configuração dos limites de estimativa de idade da Didit para políticas de restrição por idade](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/age-estimation-thresholds.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=11ffd7baa63b7193970c6b67386279f8)> [!NOTE]
>
> Esses limites podem ser ajustados conforme a sua tolerância a risco e os seus requisitos de segurança.### Restrições de idade por paísAs restrições de idade podem ser configuradas **por país**, já que a maioridade legal varia entre as jurisdições. Em vez de definir uma única idade mínima ou máxima global, você pode definir limites de idade específicos para cada país -- e até para estados ou regiões individuais dentro de um país.#### Como funciona- **Configuração por país**: defina uma idade mínima e/ou máxima para cada país (identificado pelo Estado emissor do documento). Por exemplo, você pode exigir idade mínima de 18 nos Estados Unidos, 19 na Coreia do Sul e 21 nos Emirados Árabes Unidos.
- **Exceções por estado/região**: para países com variação subnacional (como os Estados Unidos ou o México), você pode configurar exceções por estado. Por exemplo, o Mississippi pode exigir idade mínima de 21 enquanto o padrão dos EUA é 18. O sistema identifica o estado pela região extraída do documento por OCR.
- **Padrões de maioridade**: o console oferece um botão "Aplicar padrões de maioridade", de um clique, que preenche automaticamente a idade mínima de cada país com base na maioridade legal conhecida no mundo todo. Depois você pode personalizar países ou estados individuais conforme precisar.
- **Ações configuráveis**: quando a idade de um usuário fica abaixo do mínimo ou acima do máximo do país do documento, você pode escolher a ação a tomar: **Recusar** ou **Revisar**.#### Exemplo de configuração| País | Idade mín. | Idade máx. | Exceções por estado |
| - | - | - | - |
| USA | 18 | -- | Mississippi: 21, Alabama: 19 |
| KOR | 19 | -- | -- |
| GBR | 18 | 65 | -- |
| ARE | 21 | -- | -- |> [!NOTE]
>
> As restrições de idade por país estão disponíveis tanto nos fluxos de KYC padrão quanto nos fluxos de verificação de idade adaptativa. Nos fluxos adaptativos, quando a verificação de identidade é acionada em casos limítrofes, a verificação de idade usa as configurações por país definidas na etapa de verificação de identidade.## Como funciona**1. Captura de imagem ou vídeo**O usuário fornece uma imagem facial nítida por envio pela API ou conclui um processo de verificação de prova de vida.| Verificação | Descrição |
| - | - |
| **Qualidade da imagem** | Valida iluminação, posicionamento e nitidez |
| **Verificação de prova de vida** | Garante que o sujeito está presente e não é uma falsificação |
| **Análise de vários quadros** | Seleciona o melhor quadro para a máxima precisão |
| **Captura adaptativa** | Ajusta-se a diferentes capacidades de dispositivo |**2. Análise das características faciais**Um detector localiza todos os rostos e todas as pessoas na imagem, e o maior rosto é analisado.- **Recorte do rosto**: o rosto exatamente como foi detectado, analisado quanto à morfologia facial, às proporções e à textura da pele
- **Contexto corporal**: a pessoa ao redor do rosto, com o rosto mascarado, refina a estimativa
- Vários rostos em uma mesma imagem são detectados e informados, para que a sessão seja tratada de acordo**3. Processamento por redes neurais**Duas redes neurais profundas complementares estimam a idade de forma independente, e a estimativa final é a média das duas.- Um transformer lê os recortes do rosto e do corpo em conjunto; uma rede convolucional lê o rosto
- Cada rede combina cinco modelos treinados em divisões diferentes dos dados, o que estabiliza a estimativa
- Treinadas com idades confirmadas por documentos de identidade, com adolescentes, jovens adultos e todos os grupos de tom de pele bem representados
- Avaliadas somente em selfies e pessoas que os modelos nunca viram durante o treinamento**4. Decisão e análise complementar**O sistema gera um resultado completo:| Saída | Descrição |
| - | - |
| **Estimativa de idade** | Estimativa principal com pontuação de confiança |
| **Estimativa de gênero** | Contexto demográfico complementar (opcional) |
| **Métricas de confiança** | Avaliação geral de confiabilidade |
| **Fatores ambientais** | Avaliação do impacto na qualidade da estimativa |**5. Aplicação das regras**As suas regras de negócio configuradas são aplicadas aos resultados da estimativa.- A estimativa de idade é comparada com os seus **limites configurados** (mín./máx. por país)
- As pontuações de confiança são conferidas com os seus requisitos mínimos
- **Casos limítrofes** podem acionar a alternativa de verificação de identidade (modo adaptativo)
- Os resultados ficam documentados em uma **trilha de auditoria** detalhada para conformidade## Estimativa de idade adaptativaEm cenários em que a verificação precisa da idade é crítica, nossa plataforma oferece a estimativa de idade adaptativa, com alternativa de verificação de identidade. Essa abordagem equilibra a conveniência do usuário e a conformidade regulatória.### Como funciona a estimativa de idade adaptativa**1. Estimativa de idade inicial**O sistema primeiro tenta estimar a idade do usuário por análise facial. Uma pontuação de confiança é gerada junto com a estimativa de idade.**2. Avaliação dos limites**A idade estimada é comparada com os seus limites configurados. Três resultados possíveis:| Resultado | Descrição |
| - | - |
| **Aprovação clara** | O usuário está claramente acima do limite de idade exigido |
| **Reprovação clara** | O usuário está claramente abaixo do limite de idade exigido |
| **Limítrofe** | A idade estimada cai em uma faixa incerta ou tem baixa confiança |**3. Alternativa inteligente**- **Aprovação/reprovação clara**: a verificação termina imediatamente com o resultado correspondente
- **Casos limítrofes**: o sistema inicia automaticamente um **fluxo de verificação de identidade**
- Isso garante a conformidade regulatória e minimiza o atrito para a maioria dos usuários**4. Verificação do documento (quando necessário)**Nos casos limítrofes, o usuário apresenta um documento de identidade emitido pelo governo:- A autenticidade do documento e as informações de idade são verificadas
- As **restrições de idade por país** da etapa de verificação de identidade são aplicadas
- O sistema confere a data de nascimento com a idade mínima/máxima do país e da região emissores do documento
- O retrato do documento passa por **correspondência facial 1:1 com a selfie já capturada para a estimativa de idade**, de modo que a data de nascimento do documento fica vinculada à pessoa que está diante da câmera### O que a alternativa devolveA correspondência facial da alternativa é executada sem um nó de correspondência facial no fluxo, então aparece na decisão da sessão de uma forma fácil de confundir com uma verificação que você nunca configurou:- `features` lista `FACE_MATCH` além de `AGE_ESTIMATION` e `ID_VERIFICATION` depois que a alternativa é executada.
- `face_matches[]` traz uma entrada com o `score`, a `source_image` (retrato do documento) e a `target_image` (selfie da estimativa de idade). Seu `node_id` é o do **nó de estimativa de idade** (`feature_age_estimation` em um fluxo nativo), porque a correspondência pertence a essa etapa, e não a uma etapa de correspondência facial.
- Uma pontuação baixa gera os [avisos de correspondência facial](https://docs.didit.me/core-technology/face-match/warnings-face-match.md) habituais e pode enviar a sessão para revisão ou recusa, exatamente como um nó de correspondência facial configurado faria.
- Ela **não é cobrada** como uma correspondência facial: a sessão é cobrada apenas pela estimativa de idade e pela verificação de identidade.As sessões que passam ou falham somente pela selfie nunca executam a alternativa, e por isso devolvem `face_matches: null`. Para manter as imagens fora do payload da decisão, limite os campos de `face_matches` com os [atributos de resposta](https://docs.didit.me/sessions-api/retrieve-session.md) do fluxo.> [!NOTE]
>
> A estimativa de idade adaptativa pode ser configurada com o tipo de fluxo [Adaptive Age Verification](https://docs.didit.me/console/workflows.md). Você pode definir os limites de idade limítrofes que determinam quando a verificação de identidade é acionada. A aprovação ou recusa final por idade nos casos limítrofes é então regida pelas restrições de idade por país configuradas na etapa de verificação de identidade.### Benefícios da estimativa de idade adaptativa- **Menos atrito**: a maioria dos usuários conclui a verificação apenas com uma selfie
- **Mais conformidade**: os casos incertos recebem uma verificação rigorosa de documento, com regras de idade específicas do país
- **Eficiência de custo**: a verificação de identidade só é usada quando necessário
- **Tolerância a risco personalizável**: ajuste os limites conforme os seus requisitos regulatórios
- **Ciente da jurisdição**: aplica automaticamente a maioridade correta com base no país e na região emissores do documento do usuárioEssa abordagem é especialmente valiosa para serviços com restrição de idade, como jogos online, entrega de bebidas alcoólicas e plataformas de conteúdo adulto, em que é essencial equilibrar a experiência do usuário e a conformidade regulatória.## Desempenho do modelo e estatísticasOs números abaixo vêm de uma avaliação com 51,655 selfies de pessoas de 13 anos ou mais, com a idade de cada pessoa obtida do seu documento de identidade verificado.
Cada estimativa foi produzida por um modelo que nunca tinha visto aquela selfie, nem aquela pessoa, durante o treinamento.
Os números gerais são ponderados para uma mistura de avaliação com 10% de menores de 18 anos, com adultos na distribuição de idades do tráfego real; cada faixa etária é informada separadamente abaixo.### Métricas de precisão<table>
  <thead>
    <tr>
      <th>Métrica</th>
      <th>Valor</th>
      <th>Descrição</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**Erro médio absoluto (MAE)**</td>
      <td>2.8 anos</td>
      <td>Diferença média entre a idade estimada e a idade do documento</td>
    </tr>

    <tr>
      <td>**Desvio padrão**</td>
      <td>3.0 anos</td>
      <td>Dispersão do erro absoluto de uma estimativa para outra</td>
    </tr>

    <tr>
      <td>**Precisão dentro de ±5 anos**</td>
      <td>84%</td>
      <td>Porcentagem de estimativas dentro de 5 anos da idade do documento</td>
    </tr>

    <tr>
      <td>**Precisão dentro de ±3 anos**</td>
      <td>65%</td>
      <td>Porcentagem de estimativas dentro de 3 anos da idade do documento</td>
    </tr>
  </tbody>
</table>### Desempenho por faixa etáriaO erro é menor em torno das idades em que a restrição por idade decide, e cresce com a idade.<table>
  <thead>
    <tr>
      <th>Faixa etária</th>
      <th>Selfies</th>
      <th>MAE (anos)</th>
      <th>Desvio padrão (anos)</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>13-15</td>
      <td>5,003</td>
      <td>1.24</td>
      <td>1.14</td>
    </tr>

    <tr>
      <td>16-17</td>
      <td>10,933</td>
      <td>0.90</td>
      <td>1.05</td>
    </tr>

    <tr>
      <td>18-20</td>
      <td>5,436</td>
      <td>1.81</td>
      <td>1.79</td>
    </tr>

    <tr>
      <td>21-25</td>
      <td>8,640</td>
      <td>2.29</td>
      <td>1.90</td>
    </tr>

    <tr>
      <td>26-40</td>
      <td>15,182</td>
      <td>2.95</td>
      <td>2.39</td>
    </tr>

    <tr>
      <td>41-60</td>
      <td>5,830</td>
      <td>3.62</td>
      <td>3.27</td>
    </tr>

    <tr>
      <td>Mais de 60</td>
      <td>631</td>
      <td>6.53</td>
      <td>8.64</td>
    </tr>
  </tbody>
</table>> [!NOTE]
>
> O desvio padrão descreve quanto varia o erro das estimativas individuais, e não a incerteza da média.
> Uma estimativa a um ou dois anos da sua idade mínima pode cair de qualquer lado dela: quando uma decisão errada perto do limite importa, envie essa faixa limítrofe para a [alternativa adaptativa de verificação de identidade](#estimativa-de-idade-adaptativa).


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