> ## 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: 셀피 기반 연령 확인 > Didit의 연령 추정 API입니다. POST /v3/age-estimation/으로 신분증 없이 AI 연령 추정과 내장 패시브 라이브니스 감지를 제공합니다. 추론 2s 미만, 사용량 기반 요금. ## OpenAPI ````yaml ko/openapi-25.json POST /v3/age-estimation/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: 신분증 인증 API입니다. x-api-key 헤더로 인증합니다. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/age-estimation/: post: tags: - Standalone APIs summary: 연령 추정(얼굴 연령 + 패시브 라이브니스) description: >- 단일 얼굴 사진에서 인물의 연령을 추정하고 동일한 호출 내에서 수동적 라이브니스 검사를 실행합니다. 모델이 예측한 `age_estimation`(연 단위), 라이브니스 `score`(0–100), 그리고 `Approved`/`Declined` `status`를 반환합니다. 연령은 **문서를 통해 검증된 것이 아니라 얼굴로부터 모델이 예측한 값**입니다. 법적 연령 증명이 아닌 연령 제한 게이트 및 마찰이 적은 검사용으로 사용하십시오. **작동 방식.** 이미지에서 얼굴을 분석합니다(촬영 방향이 옆으로 눕혀져 있거나 거꾸로인 경우 `rotate_image=true` 설정). 감지된 각 얼굴의 연령이 추정되며, 프레임에서 가장 큰 얼굴을 기준으로 `age_estimation`이 결정됩니다. 동시에 수동적 라이브니스 모델이 사진 속 인물이 실제 인물인지 점수를 매기며(사용자 챌린지 불필요), 프레젠테이션 공격(사진의 사진, 화면, 마스크)을 감지합니다. 최상의 결과를 위해 이미지당 조명이 밝은 환경에서 촬영한 선명하고 정면을 바라보는 얼굴 하나를 전송하십시오. **결정 로직.** 경고가 하나라도 있으면 거부됩니다. `warnings` 배열이 비어 있을 때만 `status`가 `Approved`가 됩니다. 라이브니스 `score`가 `face_liveness_score_decline_threshold`(기본값 `30`) 이하이면 `LOW_LIVENESS_SCORE`가 추가됩니다. 공격이 감지되면 `LIVENESS_FACE_ATTACK`이 추가되고, 라이브니스 모델에서 얼굴을 찾지 못하면 `NO_FACE_DETECTED`가 추가되며, 추정 가능한 얼굴 연령이 없으면 `AGE_NOT_DETECTED`가 추가됩니다(`age_estimation`은 `null`). 추정 연령이 `age_estimation_decline_threshold`(기본값 `18`) 미만이면 `AGE_BELOW_MINIMUM`이 추가됩니다. 설정한 임계값에 가까운 경계선 연령은 문서 기반 인증으로 대체하는 것이 좋습니다. 한계치에 가까운 얼굴일수록 모델의 오차가 커지기 때문입니다. **결제.** `200` 응답마다 연령 추정 API 크레딧 1개가 차감됩니다(요금제 크레딧 또는 충전 잔액에서 차감). 조직의 잔액이 호출 비용을 충당할 수 없는 경우, endpoint는 이미지 처리가 시작되기 전에 크레딧 부족 오류와 함께 `403`을 반환합니다. **세션 영속성 (`save_api_request`, 기본값 `true`).** `true`인 경우 호출이 API 유형 세션으로 저장됩니다. Business Console에 표시되며, 반환된 `request_id`는 `GET /v3/session/{sessionId}/decision/`에 전달할 수 있는 실제 세션 id가 됩니다(결과는 해당 위치의 `liveness_checks[]` 내에 `features: ["AGE_ESTIMATION"]`과 함께 표시됨). 얼굴 크롭 및 참조 이미지가 저장되고, 얼굴 임베딩이 애플리케이션의 얼굴 색인에 추가되며(얼굴 검색 및 중복 감지에 사용), `status.updated` webhook이 발송됩니다. `false`인 경우 아무것도 저장되지 않으며 `request_id`는 나중에 조회할 수 없는 일회성 상관관계 UUID가 됩니다. **샌드박스.** 샌드박스 API 키는 모든 처리 및 결제를 건너뜁니다. 요청 유효성 검사 후(잘못된 형식의 입력은 여전히 `400`을 반환함) endpoint는 정적 `Approved` 모의 payload(`age_estimation: 30`, 경고 없음)를 반환하며, 세션이 저장되지 않고 크레딧도 소모되지 않습니다. **인증.** 애플리케이션의 API 키를 `x-api-key` 헤더에 담아 전송하십시오. 자격 증명이 누락되었거나 유효하지 않으면 `403`(`{"detail": "You do not have permission to perform this action."}`)을 반환합니다. 이 API는 `401`을 절대 반환하지 않습니다. **속도 제한.** 모든 POST/PATCH/DELETE endpoint에 걸쳐 API 키당 분당 300회의 공유 쓰기 예산이 적용되며, 이를 초과하면 `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: >- 분석할 얼굴 사진(예: 셀피). 대상의 얼굴이 선명하게 보이고 조명이 밝은 정면 사진 한 장을 제출하십시오. 허용되는 확장자: `tiff`, `jpg`, `jpeg`, `png`, `webp`(PDF 불가). 최대 업로드 크기: **5 MB**(더 큰 파일은 `400`과 함께 거부됨). 이미지는 처리 전에 약 0.3 MB로 자동 압축되므로 매우 높은 해상도가 정확도를 향상시키지는 않습니다. face_liveness_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- 라이브니스 임계값(0–100). 라이브니스 `score`가 이 값 **이하**인 경우 `LOW_LIVENESS_SCORE` 경고를 추가하고 거부합니다. 더 엄격한 안티 스푸핑을 위해 값을 올리십시오. 0–100 범위를 벗어난 값은 `400`을 반환합니다. example: 30 age_estimation_decline_threshold: type: integer default: 18 minimum: 0 maximum: 100 description: >- 허용 가능한 최소 추정 연령(세 단위)입니다. 추정 연령이 이 값 **미만**인 경우 `AGE_BELOW_MINIMUM` 경고가 추가되고 거부됩니다. 연령 확인을 비활성화하려면 `0`으로 설정하십시오(이 경우 연령 기반 결정 없이 라이브니스 + 연령 추정만 실행됩니다). example: 18 rotate_image: type: boolean default: false description: >- `true`인 경우 서비스가 입력 이미지를 90도 단위(0, 90, 180, 270)로 시도하고 최적의 얼굴 감지 결과를 내는 방향을 사용합니다. EXIF 방향 정보가 누락된 모바일 촬영에 유용합니다. 지연 시간이 추가되므로 똑바른 이미지를 보장할 수 없는 경우에만 활성화하십시오. example: false save_api_request: type: boolean default: true description: >- `true`(기본값)인 경우 호출을 API 유형 세션으로 저장합니다. Business Console에서 확인할 수 있고 반환된 `request_id`를 사용하여 `GET /v3/session/{sessionId}/decision/`을 통해 조회할 수 있으며 `status.updated` webhook을 통해 알림이 전송되고 감지된 얼굴이 애플리케이션의 얼굴 색인에 추가됩니다. `false`인 경우 아무것도 저장되지 않으며 `request_id`는 응답 상관관계 식별 전용의 일시적인 UUID입니다. example: true vendor_data: type: string description: >- 저장된 세션에 저장되고 응답에 다시 반환되는 선택적 불투명 문자열(내부 사용자 ID, 이메일, UUID 등)입니다. API 호출을 자체 기록과 연관 짓고 나중에 세션을 필터링하는 데 사용합니다. example: user-123 metadata: type: object additionalProperties: true description: >- 세션과 함께 저장되고(`save_api_request=true`인 경우) 응답에 그대로 반환되는 선택적 JSON 객체입니다. multipart 요청에서는 JSON 인코딩된 문자열 필드(예: `metadata={"flow":"age-gate"}`)로 전송하십시오. 객체로 파싱됩니다. 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: >- 연령 추정 및 패시브 라이브니스가 완료되었습니다. `age_estimation.age_estimation`은 감지된 가장 큰 얼굴에 대해 모델이 예측한 연령(연 단위, 감지된 얼굴이 없으면 `null`)이며, `age_estimation.score`는 패시브 라이브니스 점수(0–100)입니다. `status`는 `warnings`가 비어 있는 경우에만 `Approved`입니다. 미성년자이거나 스푸핑된 캡처인 경우에도 `status: "Declined"`와 함께 `200`을 반환하므로, HTTP 코드뿐만 아니라 body도 확인하십시오. `save_api_request=true`인 경우 `request_id`는 저장된 세션 ID입니다. content: application/json: examples: Approved: summary: 실제 성인 얼굴 — 두 검사 모두 통과함 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: 추정 연령이 `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: 라이브니스 점수가 거부 임계값 이하임(스푸핑 가능성 있음) 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: >- `save_api_request=true`일 때 유지된 세션 ID(`GET /v3/session/{sessionId}/decision/`와 함께 사용 가능), 그렇지 않으면 임시 상관관계 UUID입니다. age_estimation: type: object properties: status: type: string enum: - Approved - Declined description: >- 발생한 경고가 없는 경우 `Approved`, 그렇지 않은 경우 `Declined`가 됩니다(이 endpoint에서 발생하는 모든 경고는 거부로 처리됩니다). method: type: string enum: - PASSIVE description: >- 라이브니스 방식. 이 endpoint에서는 항상 `PASSIVE`입니다(단일 이미지, 사용자 챌린지 없음). score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- 0부터 100까지의 패시브 라이브니스 점수입니다. 사진에 실제 사람이 나타나 있는지에 대한 모델의 신뢰도 점수를 나타냅니다. `face_liveness_score_decline_threshold`와 비교되며, 해당 값 이하이면 호출이 `LOW_LIVENESS_SCORE`로 거부됩니다. 라이브니스 모델이 신뢰도를 반환하지 않는 경우 `null`이며, 임계값 비교 시 null은 0으로 처리되므로 호출은 여전히 `LOW_LIVENESS_SCORE`로 거부됩니다. example: 97.5 user_image: type: object description: 분석된 이미지에 대한 얼굴 감지 결과입니다. properties: entities: type: array description: >- 감지된 얼굴당 항목 1개입니다. 얼굴이 발견되지 않으면 비어 있습니다(이 경우 `age_estimation`은 `null`이 되며 `AGE_NOT_DETECTED` 경고가 추가됩니다). items: type: object properties: age: type: number format: float description: 이 얼굴의 모델 추정 연령(세 단위)입니다. example: 27.33 bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- 처리된 이미지에서 `[x_min, y_min, x_max, y_max]` 픽셀 좌표로 표시된 감지된 얼굴의 경계 상자입니다. example: - 40 - 40 - 100 - 100 confidence: type: number format: float minimum: 0 maximum: 1 description: 얼굴 감지 신뢰도(0–1). example: 0.7177750468254089 gender: type: string description: >- 감지된 얼굴의 모델 예측 성별(`male` 또는 `female`)입니다. 정보 제공용입니다. example: male best_angle: type: integer nullable: true description: >- 가장 우수한 얼굴 감지를 생성한 회전 각도(도: 0, 90, 180 또는 270). `rotate_image=true`로 방향을 수정한 경우에만 0이 아닙니다. example: 0 age_estimation: type: number format: float nullable: true description: >- 감지된 얼굴 중 **가장 큰** 얼굴의 모델 예측 연령(세 단위)입니다. 얼굴 연령을 추정할 수 없는 경우 `null`입니다(`AGE_NOT_DETECTED` 경고가 추가되고 호출이 거부됨). example: 27.33 warnings: type: array description: >- 문제없이 승인된 경우 비어 있습니다. 항목이 하나라도 있으면 `status`가 `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: >- 기계 판독 가능한 위험 코드입니다. `NO_FACE_DETECTED` — 라이브니스 모델이 얼굴을 찾지 못함; `LOW_LIVENESS_SCORE` — 라이브니스 `score`가 `face_liveness_score_decline_threshold` 이하임; `LIVENESS_FACE_ATTACK` — 프레젠테이션 공격(사진/화면/가면)이 감지됨; `AGE_NOT_DETECTED` — 얼굴 연령을 추정할 수 없음; `AGE_BELOW_MINIMUM` — 추정 연령이 `age_estimation_decline_threshold` 미만임. `NO_FACE_DETECTED`와 `LOW_LIVENESS_SCORE`는 상호 배타적입니다 — 얼굴을 찾지 못한 경우 `NO_FACE_DETECTED`만 출력됩니다. feature: type: string enum: - LIVENESS description: 경고를 발생시킨 기능입니다. 이 endpoint에서는 항상 `LIVENESS`입니다. additional_data: type: object nullable: true additionalProperties: true description: 연령 추정 경고의 경우 항상 `null`입니다. log_type: type: string enum: - error description: >- 심각도입니다. 이 endpoint에서 생성되는 모든 경고는 `error`이며 `status`를 `Declined`로 설정합니다. short_description: type: string description: 사람이 읽을 수 있는 한 줄의 위험 요약입니다. long_description: type: string description: 위험에 대한 사람이 읽기 쉬운 설명입니다. vendor_data: type: string nullable: true description: 전송한 `vendor_data`의 에코 값 또는 `null`입니다. metadata: type: object nullable: true additionalProperties: true description: 전송한 `metadata` 객체의 에코 값 또는 `null`입니다. created_at: type: string format: date-time description: 응답이 생성된 시점의 ISO 8601 타임스탬프(UTC)입니다. '400': description: >- 유효성 검사 오류입니다. `user_image`가 누락되었거나, 5 MB를 초과하거나, 지원되지 않는 확장자이거나, 임계값이 범위를 벗어난 경우 반환됩니다. 본문은 DRF의 표준 필드 오류 봉투(문제가 있는 필드당 메시지 배열 1개)입니다. content: application/json: examples: Missing user image: summary: 폼 데이터에 `user_image`가 포함되지 않음 value: user_image: - No file was submitted. Unsupported file extension: summary: 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: 업로드가 5MB 제한을 초과함 value: user_image: - File size should not exceed 5 MB Threshold out of range: summary: '`face_liveness_score_decline_threshold`가 0–100 범위를 벗어남' value: face_liveness_score_decline_threshold: - Ensure this value is less than or equal to 100. '403': description: >- 권한이 거부되었습니다. `x-api-key` 헤더가 누락되었거나 호출한 조직의 잔액이 호출 비용을 충당할 수 없을 때 반환됩니다. 잘못되었거나 취소되었거나 만료된 키는 `401`을 반환합니다. 키가 누락된 경우 `{"detail": ...}`과 함께 `403`을 반환하고, 잘못되었거나 취소되었거나 만료된 키는 `401`을 반환합니다. 크레딧이 부족한 경우 어떠한 이미지 처리도 진행되기 전에 `{"error": ...}`과 함께 `403`을 반환합니다. content: application/json: examples: Missing or invalid API key: summary: '`x-api-key` 헤더가 없거나, 키가 유효하지 않거나 해지되었습니다' value: detail: You do not have permission to perform this action. Not enough credits: summary: 조직 잔액이 호출 비용을 충당할 수 없습니다 value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- 속도 제한을 초과했습니다. POST/PATCH/DELETE endpoint는 API 키당 분당 300회의 쓰기 요청 한도를 공유합니다(거래 생성 및 이벤트 수집은 별도로 600회 한도 적용). 응답에는 `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `Retry-After` 헤더가 포함됩니다. content: application/json: examples: Write rate limit exceeded: summary: 현재 분 동안 300건을 초과하는 쓰기 요청 발생 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: >- Business Console의 Developers -> API keys에서 발급받은 귀하 애플리케이션의 API 키입니다. 기본 키는 전체 접근 권한을 갖습니다. 이름이 지정된 키는 리소스별 none, read, write 범위로 권한을 제한할 수 있으며 특정 워크플로나 승인된 세션, IP 주소 목록, 만료일 등으로 제한할 수도 있습니다. 401은 키가 잘못되었거나 폐기되었거나 만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스나 작업에 대한 접근 권한이 없거나, 요청이 허용된 IP 목록 외부 주소에서 발생했음을 의미합니다. 세션 경로에서의 404는 해당 세션이 키의 허용 워크플로 또는 상태 범위를 벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 비디오, PDF URL을 null로 수신하며, 세션 write 권한이 없는 키는 세션 링크와 token을 null로 수신합니다. https://docs.didit.me/console/api-keys 를 참고하십시오. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.