Laporan Estimasi Usia: Skema JSON & Kolom

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

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

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.

{
  "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).

{
  "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. Bentuk respons mandiri didokumentasikan oleh AgeEstimationResponseSerializer dan disusun dalam AgeEstimationAPIView; nilai alur kerja dihasilkan oleh LivenessV3Serializer.

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

Contoh

Approved — mandiri, subjek dewasa

{
  "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

{
  "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

{
  "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 — perilaku fitur, harga, logika keputusan.
Peringatan Estimasi Usia — setiap kode risiko dan pemicu penolakan.
Referensi API mandiri — permintaan dan respons POST /v3/age-estimation/.
Model data — estimasi usia — skema kanonis untuk setiap kolom.
Liveness pasif — model liveness bersama yang digunakan dalam respons estimasi usia.

Autentikasi

Verifikasi

Pemantauan

Platform

Laporan Estimasi Usia: Skema JSON & Kolom

Gambaran umum

Tempat kemunculannya dalam respons API

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

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

Skema

Nilai status

Contoh

Approved — mandiri, subjek dewasa

Declined — mandiri, usia yang diprediksi di bawah ambang batas

Approved — disematkan dalam laporan liveness alur kerja

Catatan keamanan

Terkait

​Gambaran umum

​Tempat kemunculannya dalam respons API

​API mandiri — POST /v3/age-estimation/

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

​Skema

​Nilai status

​Contoh

​Approved — mandiri, subjek dewasa

​Declined — mandiri, usia yang diprediksi di bawah ambang batas

​Approved — disematkan dalam laporan liveness alur kerja

​Catatan keamanan

​Terkait

Gambaran umum

Tempat kemunculannya dalam respons API

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

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

Skema

Nilai status

Contoh

Approved — mandiri, subjek dewasa

Declined — mandiri, usia yang diprediksi di bawah ambang batas

Approved — disematkan dalam laporan liveness alur kerja

Catatan keamanan

Terkait