> ## 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年齢推定のレスポンスを解析する方法。推定年齢、パッシブライブネススコア、顔品質指標、却下しきい値、警告コードを解説。1回$0.10からの従量課金。

年齢推定レポートは、画像内で検出された最も大きな顔について、モデルが予測した年齢(年単位)を記録します。同時にパッシブライブネスチェックを行い、被写体が写真、画面、マスクではなく実在の人物であることを確認します。この2つのチェックは常にセットで実行され、年齢推定がライブネススコアなしで年齢を返すことはありません。

このページでは、2つの呼び出し経路が返すJSONの構造を説明します。スタンドアロンの`POST /v3/age-estimation/`エンドポイントと、ワークフローのライブネスレポートに埋め込まれる`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)

## 概要

年齢推定には2つの提供形態があります。

* **スタンドアロンAPI。** `POST /v3/age-estimation/`は顔画像1枚(`user_image`)を受け取り、予測年齢とパッシブライブネススコアを同期的に返します。詳しくは[年齢推定スタンドアロンAPIリファレンス](https://docs.didit.me/ja/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`(浮動小数点数。例: `27.33`。顔の年齢を推定できなかった場合は`null`)。
* スタンドアロンのみ: `entities[]`配列(検出された顔ごとに1件。`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/ja/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/`

スタンドアロンのレスポンスは、結果を単一のトップレベルの`age_estimation`オブジェクトにまとめ、`request_id`およびリクエストからそのまま返される`vendor_data` / `metadata`と並べて返します。`save_api_request=true`(デフォルト)の場合、`request_id`は保存されたセッションIDとなり、結果は後から判定エンドポイントでも取得できます。`false`の場合は、1回限りの相関用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の判定エンドポイントは、ライブネスレポートを複数形の配列キー**`liveness_checks`**(`ReducedSessionV3DecisionSerializer.get_liveness_checks`)に格納して返します。各エントリには`age_estimation`の浮動小数点値(検出された最も大きな顔の推定年齢)、または年齢が算出されなかった場合は`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`)も判定エンドポイントで同じ形式で返され、`features`に`AGE_ESTIMATION`が含まれます。

## スキーマ

フィールドごとの正規スキーマは[データモデル](https://docs.didit.me/ja/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[];
}
```

### ステータス値

ステータス文字列は、共通の機能ステータスenumに由来します([ステータスenum](https://docs.didit.me/ja/reference/data-models.md#ステータス列挙値リファレンス)を参照)。スタンドアロンエンドポイントが返すのは次のいずれかのみです。

| ステータス | 意味 |
| - | - |
| `Approved` | 警告は発生していません。被写体が実在の人物であり、予測年齢が設定されたしきい値を満たしています。 |
| `Declined` | 少なくとも1つの警告が発生しました。ライブネススコアが低い、年齢がしきい値未満、顔または年齢を検出できない、攻撃が検出された、のいずれかです。 |

ワークフローのセッションでは、設定可能なリスクがレビューアクションをトリガーした場合(例: `POSSIBLE_DUPLICATED_FACE`)、ライブネスチェックは`In Review`と判定されることもあります。[ステータスenumリファレンス](https://docs.didit.me/ja/reference/data-models.md#ステータス列挙値リファレンス)を参照してください。

## 例

### 承認済み: スタンドアロン、成人の被写体

```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"
}
```

### 却下: スタンドアロン、予測年齢がしきい値未満

```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"
}
```

### 承認済み: ワークフローのライブネスレポートに埋め込まれた

```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を更新するには判定エンドポイントを再度呼び出してください。ベストプラクティスとして、自社側には元の生体メディアではなく、認証ステータスと信頼度の値のみを保存してください。

## 関連情報

* [年齢推定の概要](https://docs.didit.me/ja/core-technology/age-estimation/overview.md): 機能の動作、料金、判定ロジック。
* [年齢推定の警告](https://docs.didit.me/ja/core-technology/age-estimation/warnings-age-estimation.md): すべてのリスクコードと却下のトリガー。
* [スタンドアロンAPIリファレンス](https://docs.didit.me/ja/standalone-apis/age-estimation.md): `POST /v3/age-estimation/`のリクエストとレスポンス。
* [データモデル: 年齢推定](https://docs.didit.me/ja/reference/data-models.md#年齢推定): フィールドごとの正式なスキーマ。
* [パッシブライブネス](https://docs.didit.me/ja/core-technology/liveness/overview.md): 年齢推定のレスポンスで使用される共通のライブネスモデル。


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