> ## 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: verificação por selfie > API de estimativa de idade da Didit: POST /v3/age-estimation/ com liveness passiva integrada. Sem documento, inferência abaixo de 2s, pague por uso. ## OpenAPI ````yaml pt-br/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 pelo rosto + prova de vida passiva) description: >- Estime a idade de uma pessoa a partir de uma única foto do rosto e execute uma verificação passiva de prova de vida na mesma chamada. A resposta traz a `age_estimation` prevista pelo modelo (em anos), uma `score` de prova de vida (0–100) e um `status` `Approved`/`Declined`. A idade é **prevista pelo modelo a partir do rosto, e não verificada em um documento**: use-a para restrições por idade e verificações de baixo atrito, não como prova legal de idade. **Como funciona.** A imagem é analisada em busca de rostos (defina `rotate_image=true` se as capturas puderem estar de lado ou de cabeça para baixo); cada rosto detectado recebe uma idade estimada, e o maior rosto do quadro determina a `age_estimation`. Em paralelo, um modelo passivo de prova de vida avalia se a foto mostra uma pessoa real (sem exigir nenhum desafio do usuário) e detecta ataques de apresentação (fotos de fotos, telas, máscaras). Para obter os melhores resultados, envie um rosto nítido, de frente e bem iluminado por imagem. **Lógica de decisão.** Qualquer aviso resulta em recusa: o `status` só é `Approved` quando o array `warnings` está vazio. Uma `score` de prova de vida igual ou inferior a `face_liveness_score_decline_threshold` (padrão `30`) adiciona `LOW_LIVENESS_SCORE`; um ataque detectado adiciona `LIVENESS_FACE_ATTACK`; nenhum rosto encontrado pelo modelo de prova de vida adiciona `NO_FACE_DETECTED`; nenhuma idade estimável do rosto adiciona `AGE_NOT_DETECTED` (`age_estimation` é `null`); uma idade estimada abaixo de `age_estimation_decline_threshold` (padrão `18`) adiciona `AGE_BELOW_MINIMUM`. Idades limítrofes próximas ao seu limiar merecem um fallback para verificação baseada em documento, pois o erro do modelo aumenta para rostos próximos ao limite. **Faturamento.** Cada resposta `200` consome um crédito da API de Estimativa de idade (pago com o crédito do seu plano ou com o saldo de recarga). Quando o saldo da organização não cobre a chamada, o endpoint retorna `403` com o erro de créditos insuficientes antes de qualquer processamento da imagem. **Persistência da sessão (`save_api_request`, padrão `true`).** Quando `true`, a chamada é persistida como uma sessão do tipo API: ela aparece no Business Console, o `request_id` retornado é um ID de sessão real que você pode passar para `GET /v3/session/{sessionId}/decision/` (o resultado é exposto ali 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 facial da sua aplicação (usado pela busca facial e pela detecção de duplicatas) e um webhook `status.updated` é emitido. Quando `false`, nada é armazenado e o `request_id` é um UUID de correlação avulso que não pode ser consultado depois. **Sandbox.** Chaves de API de sandbox ignoram todo o processamento e o faturamento: após a validação da requisição (entradas malformadas ainda retornam `400`), o endpoint retorna um payload simulado estático `Approved` (`age_estimation: 30`, sem avisos), nenhuma sessão é persistida e nenhum crédito é consumido. **Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais ausentes ou inválidas retornam `403` (`{"detail": "You do not have permission to perform this action."}`); esta API nunca retorna `401`. **Limite de requisições.** Cota de escrita compartilhada de 300 requisições/min por chave de API em todos os endpoints POST/PATCH/DELETE; ao excedê-la, a resposta é `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 do rosto a ser analisada (por exemplo, uma selfie). Envie uma única foto frontal com o rosto da pessoa claramente visível e bem iluminado. Extensões permitidas: `tiff`, `jpg`, `jpeg`, `png`, `webp` (sem PDF). Tamanho máximo de upload: **5 MB** (arquivos maiores são rejeitados com `400`). As imagens são comprimidas automaticamente para cerca de 0,3 MB antes do processamento, portanto 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 a verificação. Aumente esse valor para uma proteção antispoofing mais rigorosa. Valores fora do intervalo 0–100 retornam `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 **abaixo** desse valor adiciona um aviso `AGE_BELOW_MINIMUM` e recusa. Defina `0` para desativar a verificação de idade (a chamada então executa apenas prova de vida + estimativa de idade, sem decisão baseada em 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 usa a orientação que produz a melhor detecção de rosto, o que é útil para capturas móveis sem orientação EXIF. Aumenta a latência, então ative apenas se você não puder garantir imagens na posição vertical. example: false save_api_request: type: boolean default: true description: >- Quando `true` (padrão), persiste a chamada como uma sessão do tipo API: visível no Business Console, recuperável via `GET /v3/session/{sessionId}/decision/` usando o `request_id` retornado, anunciada por meio de um webhook `status.updated` e com o rosto detectado adicionado ao índice facial da sua aplicação. Quando `false`, nada é armazenado e `request_id` é um UUID transitório usado apenas para correlacionar a resposta. example: true vendor_data: type: string description: >- String opaca opcional (seu ID interno de usuário, e-mail, UUID…) armazenada na sessão persistida e devolvida na resposta. Use-a para correlacionar chamadas de API com seus próprios registros e para filtrar sessões posteriormente. 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 requisições multipart, envie-o como um campo de string codificada em JSON (por exemplo, `metadata={"flow":"age-gate"}`), que é convertido em um 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, do maior rosto detectado (`null` se não houver nenhum); `age_estimation.score` é a pontuação da prova de vida passiva (0–100); `status` é `Approved` somente quando `warnings` está vazio. Uma captura de menor de idade ou com spoofing ainda retorna `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 real — ambas as verificações 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 foi gerado; `Declined` caso contrário (todo aviso que este endpoint produz resulta em recusa). method: type: string enum: - PASSIVE description: >- Método de prova de vida. Sempre `PASSIVE` neste endpoint (imagem única, sem desafio para o usuário). 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 foto mostra uma pessoa real. É comparada com `face_liveness_score_decline_threshold`; se for igual ou inferior a esse limiar, a chamada é recusada com `LOW_LIVENESS_SCORE`. `null` quando o modelo de prova de vida não retorna confiança; a chamada ainda é recusada com `LOW_LIVENESS_SCORE`, porque null é tratado como 0 na comparação com o limiar. example: 97.5 user_image: type: object description: Resultados da detecção facial para a imagem analisada. properties: entities: type: array description: >- Uma entrada por rosto detectado. Vazio quando nenhum rosto foi encontrado (nesse caso, `age_estimation` é `null` e um aviso `AGE_NOT_DETECTED` é adicionado). items: type: object properties: age: type: number format: float description: >- Idade deste rosto estimada pelo modelo, em anos. example: 27.33 bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Caixa delimitadora do rosto detectado, como coordenadas em pixels `[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 detecção facial (0–1). example: 0.7177750468254089 gender: type: string description: >- Gênero do rosto detectado previsto pelo modelo (`male` ou `female`). Apenas informativo. example: male best_angle: type: integer nullable: true description: >- Rotação (em graus: 0, 90, 180 ou 270) que produziu a melhor detecção de rosto. Só é diferente de zero quando `rotate_image=true` corrigiu a orientação. example: 0 age_estimation: type: number format: float nullable: true description: >- Idade em anos prevista pelo modelo para o **maior** rosto detectado. `null` quando não foi possível estimar a idade de nenhum rosto (um aviso `AGE_NOT_DETECTED` é adicionado e a chamada é recusada). example: 27.33 warnings: type: array description: >- Vazio em uma aprovação sem ressalvas. 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 detectado um ataque de apresentação (foto/tela/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: >- Recurso que emitiu 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: >- Severidade. Todo aviso que este endpoint produz é `error` e define `status` como `Declined`. short_description: type: string description: Resumo legível do risco em uma linha. long_description: type: string description: Explicação legível do risco. vendor_data: type: string nullable: true description: Eco do `vendor_data` que você enviou, ou `null`. metadata: type: object nullable: true additionalProperties: true description: Eco do objeto `metadata` que você enviou, ou `null`. created_at: type: string format: date-time description: >- Timestamp ISO 8601 (UTC) do momento em que a resposta foi gerada. '400': description: >- Erro de validação. Retornado quando `user_image` está ausente, excede 5 MB ou tem uma extensão não suportada, ou quando um limiar está fora do intervalo permitido. O corpo é o envelope padrão de erros de campo do DRF: um array de mensagens para cada campo com problema. 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 arquivo 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 upload 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 do intervalo 0–100 value: face_liveness_score_decline_threshold: - Ensure this value is less than or equal to 100. '403': description: >- Permissão negada. Retornado quando o cabeçalho `x-api-key` está ausente e também quando o saldo da organização que faz a chamada não cobre a chamada; uma chave incorreta, revogada ou expirada retorna `401`. Uma chave ausente retorna `403` com `{"detail": ...}`; uma chave incorreta, revogada ou expirada retorna `401`. Créditos insuficientes retornam `403` com `{"error": ...}` antes de qualquer processamento da imagem. content: application/json: examples: Missing or invalid API key: summary: Nenhum 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 requisições excedido. Todos os endpoints POST/PATCH/DELETE compartilham uma cota de 300 requisições de escrita por minuto por chave de API. 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 requisições 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: >- Chave de API da sua aplicação, em Developers -> API keys no Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter escopo restrito: nenhum acesso, 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á errada, 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 a requisição veio de um endereço fora da sua lista de IPs; 404 em uma rota de sessão significa que a sessão está fora dos fluxos ou status da chave. Uma chave sem acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave sem permissão de escrita em sessões recebe links e tokens de sessão como null. Consulte https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.