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

# Laporan Estimasi Usia: Skema JSON & Kolom

> Respons Estimasi Usia Didit: perkiraan usia, skor liveness pasif, metrik kualitas wajah, dan kode peringatan. Mulai $0.10 per panggilan.

Laporan Estimasi Usia merekam usia yang diprediksi model (dalam tahun) untuk wajah terbesar yang terdeteksi dalam sebuah gambar, digabungkan dengan pemeriksaan liveness pasif yang mengonfirmasi bahwa subjek tersebut adalah orang asli, bukan foto, layar, atau topeng. Kedua pemeriksaan tersebut selalu berjalan bersamaan — Estimasi Usia tidak pernah menghasilkan usia tanpa skor liveness.

Halaman ini mendokumentasikan bentuk JSON yang dikembalikan oleh kedua jalur pemanggilan: endpoint mandiri `POST /v3/age-estimation/` dan kolom `age_estimation` yang disematkan pada laporan liveness alur kerja.

![Laporan estimasi usia Didit dengan prediksi usia, skor liveness pasif, dan metrik kualitas wajah](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)

## Gambaran umum

Estimasi Usia memiliki dua mode pengiriman:

* **API mandiri.** `POST /v3/age-estimation/` menerima satu gambar wajah (`user_image`) dan mengembalikan usia yang diprediksi serta skor liveness pasif secara sinkron. Lihat [referensi API mandiri Estimasi Usia](https://docs.didit.me/id/standalone-apis/age-estimation.md).
* **Disematkan dalam alur kerja.** Setiap laporan liveness alur kerja memuat usia yang diprediksi di bawah `age_estimation` — nilainya selalu diisi dari wajah terbesar yang terdeteksi. Ambang batas usia hanya *diberlakukan* (memunculkan peringatan usia) pada alur estimasi usia: alur kerja verifikasi usia adaptif atau node alur kerja `AGE_ESTIMATION`.

Setiap laporan memuat:

* `status` keseluruhan (`Approved`, `Declined`).
* `method` liveness (selalu `PASSIVE` pada API mandiri; `ACTIVE_3D` / `FLASHING` / `PASSIVE` dalam alur kerja).
* `score` liveness (0–100; semakin tinggi berarti semakin besar keyakinan bahwa subjek tersebut benar-benar hidup; `null` diperlakukan sebagai `0` untuk pemeriksaan ambang batas).
* Nilai prediksi `age_estimation` dalam tahun (float — misalnya `27.33`; `null` jika usia wajah tidak dapat diestimasi).
* Khusus mandiri: objek `user_image` dengan array `entities[]` (satu entri per wajah yang terdeteksi — `age`, `bbox`, `confidence`, `gender`) dan orientasi `best_angle`.
* Khusus alur kerja: `reference_image`, `video_url`, `matches[]`, serta metrik kualitas liveness pasif `face_quality` (0–100%) dan `face_luminance` (0–100%). Respons mandiri **tidak** menyertakan kolom-kolom ini.
* Array `warnings[]` — event risiko yang dikeluarkan selama pemeriksaan (lihat [peringatan Estimasi Usia](https://docs.didit.me/id/core-technology/age-estimation/warnings-age-estimation.md)).

Keputusan mandiri bernilai `Declined` setiap kali `warnings` tidak kosong — `Approved` memerlukan array kosong. Peringatan terpicu ketika:

* `score` liveness berada pada atau di bawah `face_liveness_score_decline_threshold` (default `30`) — `LOW_LIVENESS_SCORE`.
* Usia yang diprediksi berada di bawah `age_estimation_decline_threshold` (default `18`) — `AGE_BELOW_MINIMUM`. Atur ambang batas ke `0` untuk menonaktifkan pemeriksaan usia.
* Tidak ada wajah yang terdeteksi (`NO_FACE_DETECTED`) atau usia wajah tidak dapat diestimasi (`AGE_NOT_DETECTED`).
* Model liveness menandai adanya serangan presentasi (`LIVENESS_FACE_ATTACK`).

## Tempat kemunculannya dalam respons API

### API mandiri — `POST /v3/age-estimation/`

Respons mandiri membungkus hasil di bawah satu objek `age_estimation` tingkat atas, berdampingan dengan `request_id` dan `vendor_data` / `metadata` yang ditampilkan kembali. Ketika `save_api_request=true` (default), `request_id` adalah ID sesi yang disimpan dan hasilnya juga dapat diambil nanti dari endpoint keputusan; ketika `false`, nilainya adalah UUID korelasi sekali pakai.

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

### Keputusan alur kerja — `GET /v3/session/{session_id}/decision/`

Dalam sesi alur kerja, usia yang diprediksi **disematkan di dalam laporan liveness — tidak ada array estimasi usia yang terpisah**. Endpoint keputusan V3 mengembalikan laporan liveness di bawah kunci array berbentuk jamak **`liveness_checks`** (`ReducedSessionV3DecisionSerializer.get_liveness_checks`), dan setiap entri memuat float `age_estimation` — perkiraan usia dari wajah terbesar yang terdeteksi — atau `null` jika tidak ada usia yang dihitung (`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,
      "...": "..."
    }
  ]
}
```

Baca usia dari `liveness_checks[].age_estimation`. Panggilan mandiri yang disimpan (`save_api_request=true`) muncul dengan cara yang sama pada endpoint keputusan, dengan `features` berisi `AGE_ESTIMATION`.

## Skema

Skema kanonis untuk setiap kolom tersedia di halaman [Model data](https://docs.didit.me/id/reference/data-models.md#estimasi-usia). Bentuk respons mandiri didokumentasikan oleh `AgeEstimationResponseSerializer` dan disusun dalam `AgeEstimationAPIView`; nilai alur kerja dihasilkan oleh `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[];
}
```

### Nilai status

String status berasal dari enum status fitur bersama (lihat [Enum status](https://docs.didit.me/id/reference/data-models.md#referensi-enum-status)). Endpoint mandiri hanya mengembalikan:

| Status | Makna |
| - | - |
| `Approved` | Tidak ada peringatan yang terpicu — subjek hidup dan usia yang diprediksi memenuhi ambang batas yang dikonfigurasi. |
| `Declined` | Setidaknya satu peringatan terpicu — skor liveness rendah, usia di bawah ambang batas, tidak ada wajah, tidak ada usia, atau serangan. |

Dalam sesi alur kerja, pemeriksaan liveness juga dapat berstatus `In Review` ketika risiko yang dapat dikonfigurasi terpicu dengan tindakan peninjauan (misalnya `POSSIBLE_DUPLICATED_FACE`). Lihat [referensi enum status](https://docs.didit.me/id/reference/data-models.md#referensi-enum-status).

## Contoh

### Approved — mandiri, subjek dewasa

```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 — mandiri, usia yang diprediksi di bawah ambang batas

```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 — disematkan dalam laporan liveness alur kerja

```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": []
}
```

## Catatan keamanan

Semua URL gambar dan video yang dikembalikan dalam respons merupakan tautan yang telah ditandatangani sebelumnya dan memiliki masa berlaku terbatas. Perlakukan tautan ini sebagai referensi berumur pendek — jangan membagikannya secara publik, dan panggil kembali endpoint keputusan untuk menyegarkan URL yang kedaluwarsa. Sebagai praktik terbaik, simpan hanya status verifikasi dan nilai keyakinan di sisi Anda daripada media biometrik dasarnya.

## Terkait

* [Gambaran umum Estimasi Usia](https://docs.didit.me/id/core-technology/age-estimation/overview.md) — perilaku fitur, harga, logika keputusan.
* [Peringatan Estimasi Usia](https://docs.didit.me/id/core-technology/age-estimation/warnings-age-estimation.md) — setiap kode risiko dan pemicu penolakan.
* [Referensi API mandiri](https://docs.didit.me/id/standalone-apis/age-estimation.md) — permintaan dan respons `POST /v3/age-estimation/`.
* [Model data — estimasi usia](https://docs.didit.me/id/reference/data-models.md#estimasi-usia) — skema kanonis untuk setiap kolom.
* [Liveness pasif](https://docs.didit.me/id/core-technology/liveness/overview.md) — model liveness bersama yang digunakan dalam respons estimasi usia.


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