> ## 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 d'estimació d'edat: verificació d'edat amb selfie > Estimació d'edat amb IA i prova de vida passiva a POST /v3/age-estimation/ de Didit. Sense ID i en menys de 2s, amb preu per verificació. ## OpenAPI ````yaml ca/openapi-25.json POST /v3/age-estimation/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificació d'identitat. Autentica't amb la capçalera x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/age-estimation/: post: tags: - Standalone APIs summary: Estimació d'edat (edat facial + prova de vida passiva) description: >- Estima l'edat d'una persona a partir d'una sola foto de la cara i fa una prova de vida passiva en la mateixa crida — retorna el valor `age_estimation` predit pel model (en anys), una `score` de prova de vida (0–100) i un `status` `Approved`/`Declined`. L'edat està **predita pel model a partir de la cara, no verificada contra un document** — utilitza-la per a controls d'edat i comprovacions de baixa fricció, no com a prova legal d'edat. **Com funciona.** S'analitza la imatge per detectar cares (defineix `rotate_image=true` si les captures poden estar de costat o cap per avall); cada cara detectada rep una edat estimada, i la cara més gran de l'enquadrament determina `age_estimation`. En paral·lel, un model de prova de vida passiva puntua si la foto mostra una persona real (sense requerir cap repte a l'usuari) i detecta atacs de presentació (fotos de fotos, pantalles, màscares). Envia una sola cara clara, frontal i ben il·luminada per imatge per obtenir els millors resultats. **Lògica de decisió.** Qualsevol advertència comporta el rebuig: l'`status` és `Approved` només quan l'array `warnings` és buit. Una `score` de prova de vida igual o inferior a `face_liveness_score_decline_threshold` (per defecte `30`) afegeix `LOW_LIVENESS_SCORE`; un atac detectat afegeix `LIVENESS_FACE_ATTACK`; si el model de prova de vida no troba cap cara s'afegeix `NO_FACE_DETECTED`; si no es pot estimar l'edat de la cara s'afegeix `AGE_NOT_DETECTED` (`age_estimation` és `null`); una edat estimada per sota de `age_estimation_decline_threshold` (per defecte `18`) afegeix `AGE_BELOW_MINIMUM`. Les edats dubtoses properes al teu llindar mereixen una alternativa basada en la verificació de documents — l'error del model augmenta per a cares properes al límit. **Facturació.** Cada resposta `200` consumeix un crèdit de l'API d'Estimació d'edat (pagat amb el crèdit del teu pla o amb el saldo de recàrrega). Quan el saldo de l'organització no pot cobrir la crida, l'endpoint retorna `403` amb l'error de crèdits insuficients abans de qualsevol processament d'imatge. **Persistència de la sessió (`save_api_request`, per defecte `true`).** Quan és `true`, la crida es persisteix com una sessió de tipus API: apareix a la Business Console, el `request_id` retornat és un identificador de sessió real que pots passar a `GET /v3/session/{sessionId}/decision/` (el resultat s'exposa allà a `liveness_checks[]`, amb `features: ["AGE_ESTIMATION"]`), la retallada de la cara i la imatge de referència s'emmagatzemen, l'embedding facial s'afegeix a l'índex de cares de la teva aplicació (utilitzat per la cerca facial i la detecció de duplicats) i s'emet un webhook `status.updated`. Quan és `false`, no s'emmagatzema res i `request_id` és un UUID de correlació d'un sol ús que no es pot consultar posteriorment. **Sandbox.** Les claus d'API de sandbox ometen tot el processament i la facturació: després de la validació de la sol·licitud (l'entrada mal formada continua retornant `400`), l'endpoint retorna un payload simulat estàtic `Approved` (`age_estimation: 30`, sense advertències), no es persisteix cap sessió i no es consumeixen crèdits. **Autenticació.** Envia la clau d'API de la teva aplicació a la capçalera `x-api-key`. Les credencials absents o no vàlides retornen `403` (`{"detail": "You do not have permission to perform this action."}`) — aquesta API mai retorna `401`. **Límit de freqüència.** Pressupost compartit d'escriptura de 300 sol·licituds/min per clau d'API a tots els endpoints POST/PATCH/DELETE; superar-lo retorna `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 la cara per analitzar (p. ex., una selfie). Envia una única foto frontal amb la cara de l'individu clarament visible i ben il·luminada. Extensions permeses: `tiff`, `jpg`, `jpeg`, `png`, `webp` (no s'admet PDF). Mida màxima de càrrega: **5 MB** (els fitxers més grans es rebutgen amb un error `400`). Les imatges es comprimeixen automàticament a ~0,3 MB abans del processament, de manera que resolucions molt altes no milloren la precisió. face_liveness_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Llindar de prova de vida (0–100). Una `score` de prova de vida **igual o inferior** a aquest valor afegeix una advertència `LOW_LIVENESS_SCORE` i rebutja. Augmenta'l per a una postura antisuplantació més estricta; els valors fora de 0–100 retornen `400`. example: 30 age_estimation_decline_threshold: type: integer default: 18 minimum: 0 maximum: 100 description: >- Edat estimada mínima acceptable en anys. Una edat estimada **per sota** d'aquest valor afegeix una advertència `AGE_BELOW_MINIMUM` i rebutja. Estableix `0` per desactivar la comprovació d'edat (aleshores la crida només executa la prova de vida + estimació d'edat sense una decisió basada en l'edat). example: 18 rotate_image: type: boolean default: false description: >- Quan és `true`, el servei prova la imatge d'entrada en increments de 90 graus (0, 90, 180, 270) i utilitza l'orientació que ofereix la millor detecció facial — útil per a captures mòbils a les quals falta l'orientació EXIF. Afegeix latència, de manera que activa'l només si no pots garantir imatges orientades correctament. example: false save_api_request: type: boolean default: true description: >- Quan és `true` (per defecte), manté la crida com una sessió de tipus API — visible a la Business Console, recuperable mitjançant `GET /v3/session/{sessionId}/decision/` utilitzant el `request_id` retornat, anunciada a través d'un webhook `status.updated` i amb la cara detectada afegida a l'índex facial de la teva aplicació. Quan és `false`, no s'emmagatzema res i `request_id` és un UUID transitori només per a la correlació de la resposta. example: true vendor_data: type: string description: >- Cadena opaca opcional (el teu ID d'usuari intern, correu electrònic, UUID…) desada a la sessió persistent i retornada a la resposta. Utilitza-la per correlacionar crides a l'API amb els teus propis registres i per filtrar sessions més endavant. example: user-123 metadata: type: object additionalProperties: true description: >- Objecte JSON opcional emmagatzemat amb la sessió (quan `save_api_request=true`) i retornat a la resposta. En sol·licituds multipart, envia'l com a camp de cadena codificat en JSON (p. ex., `metadata={"flow":"age-gate"}`); s'analitza com un objecte. 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: >- Estimació d'edat i prova de vida passiva completades. `age_estimation.age_estimation` és l'edat en anys predita pel model de la cara detectada més gran (`null` si no n'hi ha cap); `age_estimation.score` és la puntuació de prova de vida passiva (0–100); `status` és `Approved` només quan `warnings` està buit. Una captura d'un menor d'edat o amb suplantació continua retornant `200` amb `status: "Declined"` — inspecciona el cos, no només el codi HTTP. Quan `save_api_request=true`, `request_id` és l'id de la sessió persistida. content: application/json: examples: Approved: summary: Cara d'adult real — ambdues comprovacions superades 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: Edat estimada per sota 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: >- Puntuació de la prova de vida igual o inferior al llindar de rebuig (possible suplantació) 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 de sessió persistida quan `save_api_request=true` (utilitzable amb `GET /v3/session/{sessionId}/decision/`); en cas contrari, un UUID de correlació transitori. age_estimation: type: object properties: status: type: string enum: - Approved - Declined description: >- `Approved` quan no s'ha generat cap advertència; `Declined` en cas contrari (cada advertència que produeix aquest endpoint comporta un rebuig). method: type: string enum: - PASSIVE description: >- Mètode de prova de vida. Sempre `PASSIVE` en aquest endpoint (imatge única, sense desafiament per a l'usuari). score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Puntuació de la prova de vida passiva de 0 a 100: la confiança del model que la foto mostra una persona viva. Es compara amb `face_liveness_score_decline_threshold`; si és igual o inferior, la crida es rebutja amb `LOW_LIVENESS_SCORE`. `null` quan el model de prova de vida no retorna cap confiança; la crida igualment es rebutja amb `LOW_LIVENESS_SCORE` perquè el valor null es tracta com a 0 per a la comparació amb el llindar. example: 97.5 user_image: type: object description: >- Resultats de la detecció facial per a la imatge analitzada. properties: entities: type: array description: >- Una entrada per cara detectada. Buit quan no s'ha trobat cap cara (en aquest cas `age_estimation` és `null` i s'afegeix una advertència `AGE_NOT_DETECTED`). items: type: object properties: age: type: number format: float description: >- Edat estimada pel model d'aquesta cara, en anys. example: 27.33 bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Quadre delimitador de la cara detectada com a coordenades de píxels `[x_min, y_min, x_max, y_max]` a la imatge processada. example: - 40 - 40 - 100 - 100 confidence: type: number format: float minimum: 0 maximum: 1 description: Confiança de la detecció facial (0–1). example: 0.7177750468254089 gender: type: string description: >- Gènere predit pel model de la cara detectada (`male` o `female`). Només informatiu. example: male best_angle: type: integer nullable: true description: >- Rotació (graus: 0, 90, 180 o 270) que ha produït la millor detecció facial. Només és diferent de zero quan `rotate_image=true` ha corregit l'orientació. example: 0 age_estimation: type: number format: float nullable: true description: >- Edat prevista pel model en anys de la cara detectada **més gran**. `null` quan no s'ha pogut estimar cap edat facial (s'afegeix una advertència `AGE_NOT_DETECTED` i la crida es rebutja). example: 27.33 warnings: type: array description: >- Buit en cas d'aprovació neta. Qualsevol entrada estableix `status` a `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: >- Codi de risc llegible per màquina. `NO_FACE_DETECTED` — el model de prova de vida no ha trobat cap rostre; `LOW_LIVENESS_SCORE` — `score` de prova de vida igual o inferior a `face_liveness_score_decline_threshold`; `LIVENESS_FACE_ATTACK` — s'ha detectat un atac de presentació (foto/pantalla/màscara); `AGE_NOT_DETECTED` — no s'ha pogut estimar l'edat del rostre; `AGE_BELOW_MINIMUM` — edat estimada per sota de `age_estimation_decline_threshold`. `NO_FACE_DETECTED` i `LOW_LIVENESS_SCORE` són mútuament excloents — quan no es troba cap rostre, només s'emet `NO_FACE_DETECTED`. feature: type: string enum: - LIVENESS description: >- Funcionalitat que ha generat l'advertència. Sempre `LIVENESS` en aquest endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- Sempre `null` per a les advertències d'estimació d'edat. log_type: type: string enum: - error description: >- Gravetat. Cada advertència que produeix aquest endpoint és un `error` i estableix `status` com a `Declined`. short_description: type: string description: >- Resum d'una sola línia del risc, llegible per a humans. long_description: type: string description: Explicació fàcil de llegir del risc. vendor_data: type: string nullable: true description: Ressò de les `vendor_data` que has enviat, o `null`. metadata: type: object nullable: true additionalProperties: true description: Ressò de l'objecte `metadata` que has enviat, o `null`. created_at: type: string format: date-time description: >- Marca de temps ISO 8601 (UTC) de quan s'ha generat la resposta. '400': description: >- Error de validació. Es retorna quan falta `user_image`, supera els 5 MB, té una extensió no admesa o quan un llindar està fora de rang. El cos és l'embolcall estàndard d'errors de camp de DRF: una matriu de missatges per cada camp que conté l'error. content: application/json: examples: Missing user image: summary: '`user_image` no s''ha inclòs a les dades del formulari' value: user_image: - No file was submitted. Unsupported file extension: summary: Extensió de fitxer no permesa (només 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: La pujada supera el límit 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: >- Permís denegat. Es retorna quan falta la capçalera `x-api-key`, i també quan el saldo de l'organització que fa la crida no pot cobrir la crida; una clau incorrecta, revocada o caducada retorna `401`. Si falta la clau es retorna `403` amb `{"detail": ...}`; una clau incorrecta, revocada o caducada retorna `401`. La manca de crèdit retorna `403` amb `{"error": ...}` abans que es produeixi cap processament d'imatges. content: application/json: examples: Missing or invalid API key: summary: >- Sense capçalera `x-api-key`, o la clau no és vàlida/s'ha revocat value: detail: You do not have permission to perform this action. Not enough credits: summary: El saldo de l'organització no pot cobrir la crida value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- S'ha superat el límit de freqüència. Els endpoints POST/PATCH/DELETE comparteixen un pressupost de 300 sol·licituds d'escriptura per minut per clau d'API (la creació de transaccions i la ingesta d'esdeveniments tenen un pressupost independent de 600). La resposta inclou les capçaleres `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` i `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Més de 300 sol·licituds d'escriptura en el minut actual 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: >- La clau d'API de la teva aplicació, des de Developers -> API keys a la Business Console. La clau primària té accés complet. Una clau amb nom pot tenir l'abast limitat: cap, lectura o escriptura per recurs, limitada a determinats fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a una data de caducitat. 401 significa que la clau és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap clau, que la clau no té accés a aquest recurs o acció, o que la sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una ruta de sessió significa que la sessió està fora dels fluxos de treball o estats de la clau. Una clau sense accés a fitxers multimèdia rep els URL d'imatge, vídeo i PDF com a null, i una clau sense permís d'escriptura de sessions rep els enllaços de sessió i els tokens com a null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.