> ## 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 التي يُرجعها كلا مساري الاستدعاء: endpoint المستقل `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)

## نظرة عامة

يتوفر تقدير العمر عبر نمطي تسليم:

* **API المستقل.** يستقبل `POST /v3/age-estimation/` صورة وجه واحدة (`user_image`) ويُرجع العمر المتوقع ودرجة كشف الحيوية السلبي بشكل متزامن. راجع [مرجع API المستقل لتقدير العمر](https://docs.didit.me/ar/standalone-apis/age-estimation.md).
* **مضمن في سير العمل.** يحمل كل تقرير كشف حيوية في سير العمل العمر المتوقع ضمن `age_estimation` — ويتم ملء القيمة دائماً من أكبر وجه تم اكتشافه. لا تُطبق حدود العمر (التي تطلق تحذيرات العمر) إلا في مسارات تقدير العمر: مسارات عمل التحقق التكيفي من العمر أو عقد سير العمل من نوع `AGE_ESTIMATION`.

يحتوي كل تقرير على:

* الـ `status` العام (`Approved` أو `Declined`).
* الـ `method` الخاص بكشف الحيوية (دائماً `PASSIVE` في API المستقل؛ و`ACTIVE_3D` / `FLASHING` / `PASSIVE` في مسارات العمل).
* الـ `score` الخاص بكشف الحيوية (0–100؛ تشير القيمة الأعلى إلى ثقة أكبر في أن الشخص حي؛ وتُعامل القيمة `null` كـ `0` عند التحقق من الحدود).
* القيمة المتوقعة `age_estimation` بالسنوات (float — على سبيل المثال `27.33`؛ و`null` عندما يتعذر تقدير عمر الوجه).
* في النمط المستقل فقط: كائن `user_image` يحتوي على مصفوفة `entities[]` (إدخال واحد لكل وجه مكتشف — `age`، و`bbox`، و`confidence`، و`gender`) بالإضافة إلى اتجاه `best_angle`.
* في سير العمل فقط: `reference_image`، و`video_url`، و`matches[]`، ومقاييس جودة كشف الحيوية السلبي `face_quality` (0–100%) و`face_luminance` (0–100%). لا تتضمن استجابة النمط المستقل هذه الحقول.
* مصفوفة `warnings[]` — أحداث المخاطر الصادرة أثناء الفحص (راجع [تحذيرات تقدير العمر](https://docs.didit.me/ar/core-technology/age-estimation/warnings-age-estimation.md)).

يكون القرار في النمط المستقل `Declined` كلما كانت مصفوفة `warnings` غير فارغة — ويتطلب الحصول على `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` هو معرف الجلسة المحفوظ ويمكن أيضاً جلب النتيجة لاحقاً من 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/`

في جلسة سير العمل، يكون العمر المتوقع **مضمناً داخل تقرير كشف الحيوية — لا توجد مصفوفة منفصلة لتقدير العمر**. يُرجع endpoint القرار V3 تقارير كشف الحيوية تحت مفتاح المصفوفة بصيغة الجمع **`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/ar/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/ar/reference/data-models.md#مرجع-قيم-الحالة)). يُرجع endpoint المستقل حصراً:

| الحالة | المعنى |
| - | - |
| `Approved` | لم تنطلق أي تحذيرات — الشخص حي والعمر المتوقع يستوفي الحد المُهيّأ. |
| `Declined` | انطلق تحذير واحد على الأقل — انخفاض درجة كشف الحيوية، أو العمر أقل من الحد، أو عدم وجود وجه، أو عدم تحديد العمر، أو هجوم. |

في جلسات سير العمل، يمكن أيضاً أن تستقر نتيجة فحص كشف الحيوية على `In Review` عند انطلاق خطر قابل للتهيئة مع إجراء مراجعة (على سبيل المثال `POSSIBLE_DUPLICATED_FACE`). راجع [مرجع تعداد الحالة](https://docs.didit.me/ar/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": []
}
```

## ملاحظة أمنية

جميع روابط الصور والفيديو المرجعة في الاستجابة هي روابط موقعة مسبقاً ذات نافذة صلاحية محدودة. تعامل مع هذه الروابط كمراجع قصيرة الأجل — لا تشاركها علناً، وأعد استدعاء endpoint القرار لتحديث الروابط المنتهية الصلاحية. كأفضل ممارسة، احفظ فقط حالة التحقق وقيم الثقة من جانبك بدلاً من الوسائط البيومترية الأساسية.

## ذات صلة

* [نظرة عامة على تقدير العمر](https://docs.didit.me/ar/core-technology/age-estimation/overview.md) — سلوك الميزة، والأسعار، ومنطق اتخاذ القرار.
* [تحذيرات تقدير العمر](https://docs.didit.me/ar/core-technology/age-estimation/warnings-age-estimation.md) — جميع رموز المخاطر ومُشغِّلات الرفض.
* [مرجع API المستقل](https://docs.didit.me/ar/standalone-apis/age-estimation.md) — طلب واستجابة `POST /v3/age-estimation/`.
* [نماذج البيانات — تقدير العمر](https://docs.didit.me/ar/reference/data-models.md#تقدير-العمر) — المخطط الأساسي حقلاً بحقل.
* [كشف الحيوية السلبي](https://docs.didit.me/ar/core-technology/liveness/overview.md) — نموذج كشف الحيوية المشترك المستخدم في استجابات تقدير العمر.


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