> ## 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. # Estimativa de idade API: verificação de idade por selfie > Didit: estimativa de idade por IA com prova de vida passiva. Sem ID, inferência em menos de 2s, preço por utilização. POST /v3/age-estimation/ ## OpenAPI ````yaml pt/openapi-25.json POST /v3/age-estimation/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de Verificação de identidade. Autentique-se com o cabeçalho x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/age-estimation/: post: tags: - Standalone APIs summary: Estimativa de idade (idade facial + prova de vida passiva) description: >- Estime a idade de uma pessoa a partir de uma única fotografia do rosto e execute uma verificação de prova de vida passiva na mesma chamada — devolve o `age_estimation` previsto pelo modelo (em anos), um `score` de prova de vida (0–100) e um `status` `Approved`/`Declined`. A idade é **prevista pelo modelo a partir do rosto, não verificada contra um documento** — utilize-a para limites de idade e verificações de baixa fricção, não como prova legal de idade. **Como funciona.** A imagem é analisada para detetar rostos (defina `rotate_image=true` se as capturas puderem estar de lado ou invertidas); cada rosto detetado obtém uma idade estimada, e o maior rosto no enquadramento determina o `age_estimation`. Em paralelo, um modelo de prova de vida passiva avalia se a fotografia mostra uma pessoa viva (sem necessidade de desafio ao utilizador) e deteta ataques de apresentação (fotografias de fotografias, ecrãs, máscaras). Envie um rosto nítido, de frente e bem iluminado por imagem para obter os melhores resultados. **Lógica de decisão.** Qualquer aviso resulta numa recusa: o `status` é `Approved` apenas quando o array `warnings` está vazio. Um `score` de prova de vida igual ou inferior a `face_liveness_score_decline_threshold` (predefinição `30`) adiciona `LOW_LIVENESS_SCORE`; um ataque detetado adiciona `LIVENESS_FACE_ATTACK`; nenhum rosto encontrado pelo modelo de prova de vida adiciona `NO_FACE_DETECTED`; quando não for possível estimar a idade de um rosto, é adicionado `AGE_NOT_DETECTED` (`age_estimation` é `null`); uma idade estimada abaixo de `age_estimation_decline_threshold` (predefinição `18`) adiciona `AGE_BELOW_MINIMUM`. Idades limítrofes próximas do seu limiar justificam uma alternativa baseada em verificação por documento — o erro do modelo aumenta para rostos próximos do limite. **Faturação.** Cada resposta `200` consome um crédito da API de Estimativa de idade (pago a partir do crédito do seu plano ou do saldo carregado). Quando o saldo da organização não consegue cobrir a chamada, o endpoint devolve `403` com o erro de créditos insuficientes antes de qualquer processamento de imagem. **Persistência da sessão (`save_api_request`, predefinição `true`).** Quando `true`, a chamada é persistida como uma sessão do tipo API: aparece na Business Console, o `request_id` devolvido é um id de sessão real que pode passar para `GET /v3/session/{sessionId}/decision/` (o resultado é aí exposto em `liveness_checks[]`, com `features: ["AGE_ESTIMATION"]`), o recorte do rosto e a imagem de referência são armazenados, o embedding facial é adicionado ao índice de rostos da sua aplicação (utilizado pela pesquisa facial e deteção de duplicados) e é emitido um webhook `status.updated`. Quando `false`, nada é armazenado e `request_id` é um UUID de correlação pontual que não pode ser consultado mais tarde. **Sandbox.** As chaves de API de sandbox ignoram todo o processamento e faturação: após a validação do pedido (dados de entrada mal formatados continuam a devolver `400`), o endpoint devolve um payload simulado estático `Approved` (`age_estimation: 30`, sem avisos), nenhuma sessão é persistida e não são consumidos créditos. **Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais em falta ou inválidas devolvem `403` (`{"detail": "You do not have permission to perform this action."}`) — esta API nunca devolve `401`. **Limite de pedidos.** Orçamento de escrita partilhado de 300 pedidos/min por chave de API em todos os endpoints POST/PATCH/DELETE; excedê-lo devolve `429`. operationId: post_v3age-estimation parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image properties: user_image: type: string format: binary description: >- Foto de rosto a analisar (por exemplo, uma selfie). Envie uma única foto virada para a frente com o rosto do titular claramente visível e bem iluminado. Extensões permitidas: `tiff`, `jpg`, `jpeg`, `png`, `webp` (sem PDF). Tamanho máximo de carregamento: **5 MB** (ficheiros maiores são rejeitados com `400`). As imagens são automaticamente comprimidas para ~0.3 MB antes do processamento, pelo que resoluções muito altas não melhoram a precisão. face_liveness_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Limiar de prova de vida (0–100). Um `score` de prova de vida **igual ou inferior** a este valor adiciona um aviso `LOW_LIVENESS_SCORE` e recusa. Aumente-o para um antispoofing mais rigoroso; valores fora de 0–100 devolvem `400`. example: 30 age_estimation_decline_threshold: type: integer default: 18 minimum: 0 maximum: 100 description: >- Idade estimada mínima aceitável em anos. Uma idade estimada **inferior** a este valor adiciona um aviso `AGE_BELOW_MINIMUM` e recusa. Defina `0` para desativar a verificação de idade (a chamada executará apenas a prova de vida + estimativa de idade sem uma decisão baseada na idade). example: 18 rotate_image: type: boolean default: false description: >- Quando `true`, o serviço testa a imagem de entrada em incrementos de 90 graus (0, 90, 180, 270) e utiliza a orientação que produzir a melhor deteção facial — útil para capturas móveis sem orientação EXIF. Adiciona latência, pelo que só deve ativá-lo se não puder garantir imagens na orientação correta. example: false save_api_request: type: boolean default: true description: >- Quando for `true` (predefinição), persiste a chamada como uma sessão do tipo API — visível na Business Console, recuperável através de `GET /v3/session/{sessionId}/decision/` utilizando o `request_id` devolvido, anunciada através de um webhook `status.updated` e com o rosto detetado adicionado ao índice facial da sua aplicação. Quando for `false`, nada é armazenado e `request_id` é um UUID transitório apenas para correlação de respostas. example: true vendor_data: type: string description: >- String opaca opcional (o seu ID de utilizador interno, e-mail, UUID...) guardada na sessão persistida e devolvida na resposta. Utilize-a para correlacionar chamadas de API com os seus próprios registos e para filtrar sessões mais tarde. example: user-123 metadata: type: object additionalProperties: true description: >- Objeto JSON opcional armazenado com a sessão (quando `save_api_request=true`) e devolvido na resposta. Em pedidos multipart, envie-o como um campo de texto codificado em JSON (por exemplo, `metadata={"flow":"age-gate"}`) — é convertido num objeto. example: flow: age-gate example: user_image: (binary JPEG/PNG of the selfie) face_liveness_score_decline_threshold: 30 age_estimation_decline_threshold: 18 rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: age-gate responses: '200': description: >- Estimativa de idade e prova de vida passiva concluídas. `age_estimation.age_estimation` é a idade prevista pelo modelo em anos para o maior rosto detetado (`null` se não houver nenhum); `age_estimation.score` é a pontuação de prova de vida passiva (0–100); `status` é `Approved` apenas quando `warnings` está vazio. Uma captura de um menor ou com spoofing continua a devolver `200` com `status: "Declined"` — inspecione o corpo, não apenas o código HTTP. Quando `save_api_request=true`, `request_id` é o id da sessão persistida. content: application/json: examples: Approved: summary: >- Rosto adulto com prova de vida — ambas as verificações foram aprovadas value: request_id: 0c40ba43-64ab-4e2e-b4b8-7d1f12f81bc1 age_estimation: status: Approved method: PASSIVE score: 97.5 user_image: entities: - age: 27.33 bbox: - 40 - 40 - 100 - 100 confidence: 0.7177750468254089 gender: male best_angle: 0 age_estimation: 27.33 warnings: [] vendor_data: user-123 metadata: flow: age-gate created_at: '2026-06-12T02:24:11.512941+00:00' Declined - age below threshold: summary: Idade estimada abaixo de `age_estimation_decline_threshold` value: request_id: 9be41a6f-2f4e-4f57-92f4-b3a4f6f0a1c2 age_estimation: status: Declined method: PASSIVE score: 95 user_image: entities: - age: 16.5 bbox: - 40 - 40 - 100 - 100 confidence: 0.7177750468254089 gender: female best_angle: 0 age_estimation: 16.5 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-123 metadata: null created_at: '2026-06-12T02:26:40.118332+00:00' Declined - liveness too low: summary: >- Pontuação de prova de vida igual ou inferior ao limiar de recusa (possível spoofing) value: request_id: 5f6f2f1f-7c4f-43b9-8d62-0a8f4c2d9e77 age_estimation: status: Declined method: PASSIVE score: 5 user_image: entities: - age: 25 bbox: - 40 - 40 - 100 - 100 confidence: 0.7177750468254089 gender: male best_angle: 0 age_estimation: 25 warnings: - risk: LOW_LIVENESS_SCORE feature: LIVENESS additional_data: null log_type: error short_description: Low liveness score long_description: >- The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:27:02.901547+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- ID da sessão persistida quando `save_api_request=true` (utilizável com `GET /v3/session/{sessionId}/decision/`); caso contrário, um UUID de correlação transitório. age_estimation: type: object properties: status: type: string enum: - Approved - Declined description: >- `Approved` quando nenhum aviso tiver sido emitido; `Declined` caso contrário (todos os avisos gerados por este endpoint resultam em recusa). method: type: string enum: - PASSIVE description: >- Método de prova de vida. Sempre `PASSIVE` neste endpoint (imagem única, sem desafio ao utilizador). score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Pontuação de prova de vida passiva de 0 a 100 — a confiança do modelo de que a fotografia mostra uma pessoa viva. Comparada com `face_liveness_score_decline_threshold`; com valor igual ou inferior, a chamada é recusada com `LOW_LIVENESS_SCORE`. `null` quando o modelo de prova de vida não devolve qualquer confiança — a chamada continua a ser recusada com `LOW_LIVENESS_SCORE`, pois null é tratado como 0 para a comparação com o limiar. example: 97.5 user_image: type: object description: Resultados da deteção facial para a imagem analisada. properties: entities: type: array description: >- Uma entrada por rosto detetado. Vazio quando nenhum rosto foi encontrado (nesse caso, `age_estimation` é `null` e é adicionado um aviso `AGE_NOT_DETECTED`). items: type: object properties: age: type: number format: float description: >- Idade estimada pelo modelo para este rosto, em anos. example: 27.33 bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Caixa delimitadora do rosto detetado como coordenadas de píxeis `[x_min, y_min, x_max, y_max]` na imagem processada. example: - 40 - 40 - 100 - 100 confidence: type: number format: float minimum: 0 maximum: 1 description: Confiança da deteção facial (0–1). example: 0.7177750468254089 gender: type: string description: >- Género previsto pelo modelo para o rosto detetado (`male` ou `female`). Apenas informativo. example: male best_angle: type: integer nullable: true description: >- Rotação (graus: 0, 90, 180 ou 270) que produziu a melhor deteção facial. Diferente de zero apenas quando `rotate_image=true` corrigiu a orientação. example: 0 age_estimation: type: number format: float nullable: true description: >- Idade prevista pelo modelo, em anos, para o **maior** rosto detetado. `null` quando não foi possível estimar a idade do rosto (é adicionado um aviso `AGE_NOT_DETECTED` e a chamada é recusada). example: 27.33 warnings: type: array description: >- Vazio numa aprovação limpa. Qualquer entrada define `status` como `Declined`. items: type: object properties: risk: type: string enum: - NO_FACE_DETECTED - LOW_LIVENESS_SCORE - LIVENESS_FACE_ATTACK - AGE_NOT_DETECTED - AGE_BELOW_MINIMUM description: >- Código de risco legível por máquina. `NO_FACE_DETECTED` — o modelo de prova de vida não encontrou nenhum rosto; `LOW_LIVENESS_SCORE` — `score` de prova de vida igual ou inferior a `face_liveness_score_decline_threshold`; `LIVENESS_FACE_ATTACK` — foi detetado um ataque de apresentação (fotografia/ecrã/máscara); `AGE_NOT_DETECTED` — não foi possível estimar a idade do rosto; `AGE_BELOW_MINIMUM` — idade estimada abaixo de `age_estimation_decline_threshold`. `NO_FACE_DETECTED` e `LOW_LIVENESS_SCORE` são mutuamente exclusivos — quando nenhum rosto é encontrado, apenas `NO_FACE_DETECTED` é emitido. feature: type: string enum: - LIVENESS description: >- Funcionalidade que gerou o aviso. Sempre `LIVENESS` neste endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- Sempre `null` para avisos de estimativa de idade. log_type: type: string enum: - error description: >- Gravidade. Todos os avisos produzidos por este endpoint são um `error` e definem o `status` como `Declined`. short_description: type: string description: >- Resumo de uma linha legível por humanos sobre o risco. long_description: type: string description: Explicação legível do risco. vendor_data: type: string nullable: true description: Eco do `vendor_data` que enviou, ou `null`. metadata: type: object nullable: true additionalProperties: true description: Eco do objeto `metadata` que enviou, ou `null`. created_at: type: string format: date-time description: >- Carimbo de data/hora ISO 8601 (UTC) de quando a resposta foi gerada. '400': description: >- Erro de validação. Devolvido quando `user_image` está em falta, excede 5 MB, tem uma extensão não suportada ou quando um limiar está fora do intervalo. O corpo é o envelope padrão de erro de campo do DRF: um array de mensagens por campo afetado. content: application/json: examples: Missing user image: summary: '`user_image` não incluído nos dados do formulário' value: user_image: - No file was submitted. Unsupported file extension: summary: Extensão de ficheiro fora de tiff/jpg/jpeg/png/webp value: user_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp. File too large: summary: O carregamento excede o limite de 5 MB value: user_image: - File size should not exceed 5 MB Threshold out of range: summary: '`face_liveness_score_decline_threshold` fora de 0–100' value: face_liveness_score_decline_threshold: - Ensure this value is less than or equal to 100. '403': description: >- Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta e também quando o saldo da organização que efetua a chamada não consegue cobrir a chamada; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{"detail": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. A insuficiência de créditos devolve `403` com `{"error": ...}` antes de qualquer processamento de imagens ocorrer. content: application/json: examples: Missing or invalid API key: summary: Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada value: detail: You do not have permission to perform this action. Not enough credits: summary: O saldo da organização não cobre a chamada value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Mais de 300 pedidos de escrita no minuto atual value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- 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 'face_liveness_score_decline_threshold=30' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.age_estimation.estimate( user_image=open("user_image.jpg", "rb"), face_liveness_score_decline_threshold=30.0, age_estimation_decline_threshold=18, rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "age-gate"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.ageEstimation.estimate({ user_image: await fileFromPath("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, age_estimation_decline_threshold: 18, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "age-gate" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.AgeEstimation.Estimate(ctx, didit.AgeEstimationEstimateParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tFaceLivenessScoreDeclineThreshold: didit.Float(30.0),\n\tAgeEstimationDeclineThreshold: didit.Int(18),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"age-gate\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import java.util.Map; import me.didit.Didit; import me.didit.types.AgeEstimationEstimateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.ageEstimation().estimate(AgeEstimationEstimateParams.builder() .userImage(Path.of("user_image.jpg")) .faceLivenessScoreDeclineThreshold(30.0) .ageEstimationDeclineThreshold(18L) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "age-gate")) .build()); System.out.println(result); - lang: php label: PHP source: |- ageEstimation->estimate([ 'user_image' => File::fromPath('user_image.jpg'), 'face_liveness_score_decline_threshold' => 30.0, 'age_estimation_decline_threshold' => 18, 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'age-gate'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.age_estimation.estimate( user_image: Pathname("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, age_estimation_decline_threshold: 18, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "age-gate" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.AgeEstimation.EstimateAsync(new AgeEstimationEstimateParams { UserImage = FileUpload.FromPath("user_image.jpg"), FaceLivenessScoreDeclineThreshold = 30.0, AgeEstimationDeclineThreshold = 18, RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "age-gate" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está incorreta, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.