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

# 연령 추정 보고서: JSON 스키마 및 필드

> Didit 연령 추정 응답을 파싱하여 추정 연령, 패시브 라이브니스 점수, 얼굴 품질 지표, 거부 임계값 및 경고 코드를 확인하세요. 호출당 $0.10부터 제공됩니다.

연령 추정 보고서는 이미지에서 감지된 가장 큰 얼굴에 대해 모델이 예측한 연령(세 단위)을 기록하며, 대상자가 사진, 화면 또는 가면이 아닌 실제 사람인지 확인하는 패시브 라이브니스 검사와 함께 제공됩니다. 두 검사는 항상 함께 실행되며, 연령 추정은 라이브니스 점수 없이 연령만을 단독으로 반환하지 않습니다.

이 페이지에서는 두 가지 호출 경로에서 반환되는 JSON 형태를 설명합니다: 독립형 `POST /v3/age-estimation/` endpoint 및 워크플로 라이브니스 보고서에 임베드된 `age_estimation` 필드.

![예측 연령, 패시브 라이브니스 점수 및 얼굴 품질 지표가 포함된 Didit 연령 추정 보고서](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/age-estimation-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=f0ae767c591e55866d0cf5496291e17b)

## 개요

연령 추정에는 두 가지 전송 모드가 있습니다:

* **독립형 API.** `POST /v3/age-estimation/`은 단일 얼굴 이미지(`user_image`)를 수신하고 예측 연령과 패시브 라이브니스 점수를 동기식으로 반환합니다. [연령 추정 독립형 API 레퍼런스](https://docs.didit.me/ko/standalone-apis/age-estimation.md)를 참조하세요.
* **워크플로에 임베드됨.** 모든 워크플로 라이브니스 보고서의 `age_estimation` 아래에 예측 연령이 포함되며, 이 값은 항상 감지된 가장 큰 얼굴에서 추출됩니다. 연령 임계값은 적응형 연령 인증 워크플로 또는 `AGE_ESTIMATION` 워크플로 노드와 같은 연령 추정 흐름에서만 *적용*되어 연령 경고를 발생시킵니다.

각 보고서에는 다음 항목이 포함됩니다:

* 전반적인 `status` (`Approved`, `Declined`).
* 라이브니스 `method` (독립형 API에서는 항상 `PASSIVE`, 워크플로에서는 `ACTIVE_3D` / `FLASHING` / `PASSIVE`).
* 라이브니스 `score` (0–100, 높을수록 대상자가 실제 사람이라는 신뢰도가 높음, 임계값 확인 시 `null`은 `0`으로 처리됨).
* 예측된 `age_estimation` 연령(부동 소수점(float) 형태, 예: `27.33`, 얼굴 연령을 추정할 수 없는 경우 `null`).
* 독립형 전용: `entities[]` 배열(감지된 얼굴당 하나의 항목 — `age`, `bbox`, `confidence`, `gender`)과 `best_angle` 방향이 포함된 `user_image` 객체.
* 워크플로 전용: `reference_image`, `video_url`, `matches[]`, 그리고 패시브 라이브니스 품질 지표인 `face_quality`(0–100%) 및 `face_luminance`(0–100%). 독립형 응답에는 이러한 필드가 포함되지 **않습니다**.
* `warnings[]` 배열 — 검사 중 발생한 위험 이벤트([연령 추정 경고](https://docs.didit.me/ko/core-technology/age-estimation/warnings-age-estimation.md) 참조).

`warnings`가 비어 있지 않으면 독립형 결정은 항상 `Declined`가 되며, `Approved`가 되려면 배열이 비어 있어야 합니다. 경고는 다음과 같은 경우에 발생합니다:

* 라이브니스 `score`가 `face_liveness_score_decline_threshold`(기본값 `30`) 이하인 경우 — `LOW_LIVENESS_SCORE`.
* 예측 연령이 `age_estimation_decline_threshold`(기본값 `18`) 미만인 경우 — `AGE_BELOW_MINIMUM`. 연령 검사를 비활성화하려면 임계값을 `0`으로 설정하세요.
* 얼굴이 감지되지 않거나(`NO_FACE_DETECTED`), 얼굴 연령을 추정할 수 없는 경우(`AGE_NOT_DETECTED`).
* 라이브니스 모델이 프레젠테이션 공격을 표시하는 경우(`LIVENESS_FACE_ATTACK`).

## API 응답에 표시되는 위치

### 독립형 API — `POST /v3/age-estimation/`

독립형 응답은 결과를 `request_id` 및 다시 반환된 `vendor_data` / `metadata`와 함께 단일 최상위 `age_estimation` 객체 아래에 래핑합니다. `save_api_request=true`(기본값)인 경우 `request_id`는 저장된 세션 ID이며 결과는 나중에 결정 endpoint에서도 조회할 수 있습니다. `false`인 경우 일회성 상관관계 UUID입니다.

```json theme={null}
{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "age_estimation": {
    "status": "Approved",
    "method": "PASSIVE",
    "score": 97.5,
    "age_estimation": 27.33,
    "user_image": { "entities": [ /* ... */ ], "best_angle": 0 },
    "warnings": []
  },
  "vendor_data": "user-123",
  "metadata": { "flow": "age-gate" },
  "created_at": "2026-06-12T02:24:11.512941+00:00"
}
```

### 워크플로 결정 — `GET /v3/session/{session_id}/decision/`

워크플로 세션에서 예측 연령은 **라이브니스 보고서 내에 임베드되며, 별도의 연령 추정 배열은 존재하지 않습니다**. V3 결정 endpoint는 복수형 배열 키인 **`liveness_checks`**(`ReducedSessionV3DecisionSerializer.get_liveness_checks`) 아래에 라이브니스 보고서를 반환하며, 각 항목에는 감지된 가장 큰 얼굴의 추정 연령인 `age_estimation` 부동 소수점(float) 값이 포함되거나 연령이 계산되지 않은 경우 `null`이 포함됩니다(`LivenessV2Serializer.get_age_estimation`).

```json theme={null}
{
  "session_id": "11111111-1111-1111-1111-111111111111",
  "status": "Approved",
  "features": ["AGE_ESTIMATION"],
  "liveness_checks": [
    {
      "node_id": "feature_age_estimation_1",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 89.92,
      "age_estimation": 24.3,
      "...": "..."
    }
  ]
}
```

`liveness_checks[].age_estimation`에서 연령을 확인하세요. 저장된 독립형 호출(`save_api_request=true`)도 결정 endpoint에 동일한 방식으로 표시되며, 이때 `features`에는 `AGE_ESTIMATION`이 포함됩니다.

## 스키마

필드별 표준 스키마는 [데이터 모델](https://docs.didit.me/ko/reference/data-models.md#연령-추정) 페이지에 있습니다. 독립형 응답 형태는 `AgeEstimationResponseSerializer`에 문서화되어 있으며 `AgeEstimationAPIView`에서 조합됩니다. 워크플로 값은 `LivenessV3Serializer`에서 생성됩니다.

```typescript theme={null}
interface AgeEstimationStandalone {
  request_id: string;                  // Session id when save_api_request=true
  age_estimation: {
    status: "Approved" | "Declined";
    method: "PASSIVE";
    score: number | null;              // Passive liveness score (0-100); null counts as 0
    age_estimation: number | null;     // Predicted age in years of the largest face (float)
    user_image: {
      entities: Array<{
        age: number;                   // Estimated age of this face
        bbox: [number, number, number, number];  // [x_min, y_min, x_max, y_max]
        confidence: number;            // Face-detection confidence (0-1)
        gender: "male" | "female";
      }>;
      best_angle: number | null;       // Rotation (0/90/180/270) with best detection
    };
    warnings: Warning[];
  };
  vendor_data: string | null;          // Echoed from the request
  metadata: object | null;             // Echoed from the request
  created_at: string;                  // ISO 8601
}

interface WorkflowLivenessWithAge {
  node_id: string | null;
  status: "Approved" | "Declined" | "In Review";
  method: "ACTIVE_3D" | "FLASHING" | "PASSIVE";
  score: number | null;                // Liveness score (0-100)
  reference_image: string;             // Presigned URL
  video_url: string | null;            // Presigned URL (active liveness only)
  age_estimation: number | null;       // Predicted age in years (float)
  face_quality: number | null;         // 0-100% (passive liveness only)
  face_luminance: number | null;       // 0-100% (passive liveness only)
  warnings: Warning[];
  matches: FaceMatch[];
}
```

### 상태 값

상태 문자열은 공유 기능 상태 열거형에서 가져옵니다([상태 열거형](https://docs.didit.me/ko/reference/data-models.md#상태-열거형-참조) 참조). 독립형 endpoint는 다음 상태만 반환합니다:

| 상태 | 의미 |
| - | - |
| `Approved` | 경고가 발생하지 않음 — 대상자가 실제 사람이며 예측 연령이 설정된 임계값을 충족함. |
| `Declined` | 최소 하나의 경고 발생 — 낮은 라이브니스 점수, 임계값 미만의 연령, 얼굴 미감지, 연령 미감지 또는 공격. |

워크플로 세션에서는 구성 가능한 위험이 검토 작업과 함께 발생할 때(예: `POSSIBLE_DUPLICATED_FACE`) 라이브니스 검사가 `In Review`로 결정될 수도 있습니다. [상태 열거형 레퍼런스](https://docs.didit.me/ko/reference/data-models.md#상태-열거형-참조)를 참조하세요.

## 예시

### Approved — 독립형, 성인 대상자

```json theme={null}
{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "age_estimation": {
    "status": "Approved",
    "method": "PASSIVE",
    "score": 97.5,
    "age_estimation": 27.33,
    "user_image": {
      "entities": [
        { "age": 27.33, "bbox": [40, 40, 100, 100], "confidence": 0.72, "gender": "male" }
      ],
      "best_angle": 0
    },
    "warnings": []
  },
  "vendor_data": "user-123",
  "metadata": { "flow": "age-gate" },
  "created_at": "2026-06-12T02:24:11.512941+00:00"
}
```

### Declined — 독립형, 예측 연령이 임계값 미만

```json theme={null}
{
  "request_id": "b2c3d4e5-f6a7-8901-2345-67890abcdef0",
  "age_estimation": {
    "status": "Declined",
    "method": "PASSIVE",
    "score": 92.0,
    "age_estimation": 15.8,
    "user_image": {
      "entities": [
        { "age": 15.8, "bbox": [55, 60, 110, 110], "confidence": 0.81, "gender": "female" }
      ],
      "best_angle": 0
    },
    "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-456",
  "metadata": null,
  "created_at": "2026-06-12T02:26:40.118332+00:00"
}
```

### Approved — 워크플로 라이브니스 보고서에 임베드됨

```json theme={null}
{
  "node_id": "feature_age_estimation_1",
  "status": "Approved",
  "method": "PASSIVE",
  "score": 89.92,
  "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
  "video_url": null,
  "age_estimation": 24.3,
  "matches": [],
  "face_quality": 87.5,
  "face_luminance": 54.12,
  "warnings": []
}
```

## 보안 참고 사항

응답으로 반환되는 모든 이미지 및 동영상 URL은 유효 기간이 제한된 사전 서명된 링크입니다. 이러한 링크는 수명이 짧은 참조로 취급해야 하며, 공개적으로 공유하지 마시고 만료된 URL을 갱신하려면 결정 endpoint를 다시 호출하세요. 모범 사례로서 원본 생체 인식 미디어 자체보다는 인증 상태와 신뢰도 값만 시스템에 저장하는 것이 좋습니다.

## 관련 문서

* [연령 추정 개요](https://docs.didit.me/ko/core-technology/age-estimation/overview.md) — 기능 동작, 요금, 결정 로직.
* [연령 추정 경고](https://docs.didit.me/ko/core-technology/age-estimation/warnings-age-estimation.md) — 모든 위험 코드 및 거부 트리거.
* [독립형 API 레퍼런스](https://docs.didit.me/ko/standalone-apis/age-estimation.md) — `POST /v3/age-estimation/` 요청 및 응답.
* [데이터 모델 — 연령 추정](https://docs.didit.me/ko/reference/data-models.md#연령-추정) — 필드별 표준 스키마.
* [패시브 라이브니스](https://docs.didit.me/ko/core-technology/liveness/overview.md) — 연령 추정 응답에 사용되는 공유 라이브니스 모델.


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