إنتقل إلى المحتوى الرئيسي

API تقدير العمر من الصورة

ارفع صورة لاكتشاف الأشخاص والوجوه وتوقع العمر ونسبة الثقة لكل نتيجة.

عنوان URL الأساسي​

https://api.genderrecognition.com

نقطة النهاية​

POST /v1/image-gender/api/age

ترويسات الطلب​

apiKey: YOUR_API_KEY
Content-Type: multipart/form-data

محتوى الطلب​

الحقلالنوعمطلوبالوصف
filefileنعمصورة بصيغة JPEG أو PNG أو WebP أو BMP أو GIF. الحد الأقصى للحجم: 10 MB.

مثال​

curl -X POST "https://api.genderrecognition.com/v1/image-gender/api/age" \
  -H "apiKey: YOUR_API_KEY" \
  -F "file=@people.jpg"

استجابة ناجحة​

{
  "success": true,
  "detections": [
    {
      "age": 27.4,
      "probability": 99
    },
    {
      "age": 41.2,
      "probability": 94
    }
  ],
  "remainingRequests": 2999
}

حقول الاستجابة​

الحقلالنوعالوصف
successbooleanتكون true عند معالجة الصورة بنجاح.
detectionsarrayعنصر لكل وجه مكتشف له توقع للعمر.
detections[].agenumberالعمر المتوقع لهذه النتيجة، وقد يتضمن قيمة عشرية.
detections[].probabilityintegerنسبة الثقة من 0 إلى 100. راجع الملاحظة أدناه.
remainingRequestsintegerعدد طلبات API المتبقية بعد خصم هذا الطلب الناجح.

تمثل probability هنا ثقة النموذج في تصنيف الجنس لهذه النتيجة، وتُستخدم كقيمة الثقة المعروضة؛ ولا ينتج النموذج درجة ثقة منفصلة لتقدير العمر. لذلك تعني القيمة المرتفعة يقينًا أكبر بشأن الجنس، لا دقة أكبر في age.

لا تُدرج إلا النتائج التي تمكّن فيها النموذج من تصنيف الجنس بثقة. ويُستبعد الوجه ذو التوقع الملتبس أو غير المطابق من detections حتى إن اكتُشف بصريًا؛ لذلك قد يقل عدد عناصر detections عن عدد الوجوه في الصورة.

لم يتم اكتشاف عناصر​

قد تنجح المعالجة حتى إذا لم يُعثر على وجه يمكن توقعه بثقة. ويظل ذلك مستهلكًا لطلب واحد:

{
  "success": true,
  "detections": [],
  "remainingRequests": 2999
}

استجابات الأخطاء​

مفتاح API مفقود — 401 Unauthorized​

{
  "error": "API key is required"
}

مفتاح API غير صالح — 404 Not Found​

{
  "error": "Invalid API key"
}

خطأ في خدمة المصادقة — 500 Internal Server Error​

{
  "error": "Internal server error"
}

الملف مفقود — 400 Bad Request​

يجب أن يحمل حقل نموذج multipart الاسم file.

{
  "error": "No file uploaded"
}

حقل multipart غير متوقع — 400 Bad Request​

تُعاد هذه الاستجابة إذا كان اسم حقل الملف المرفوع غير file أو أُرسل أكثر من ملف ضمن حقل الملفات المفرد.

{
  "error": "Unexpected field"
}

نوع الملف غير صالح — 400 Bad Request​

{
  "error": "Invalid file type. Allowed formats: JPEG, PNG, WEBP, BMP, GIF"
}

الملف كبير جدًا — 400 Bad Request​

{
  "error": "File too large"
}

تعذر فك ترميز الصورة — 400 Bad Request​

{
  "error": "Could not decode image"
}

قد تعيد خدمة التوقع رسالة تحقق أخرى برمز 400 إذا كانت الصورة المرفوعة غير صالحة. ويظل شكل الاستجابة { "error": "..." }.

رفضت خدمة التوقع الملف الكبير — 413 Payload Too Large​

{
  "error": "Uploaded file exceeds the 10MB size limit"
}

تم تجاوز الحصة — 400 Bad Request​

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded your free tier limit of 50 requests.",
    "detailedMessage": "Insufficient remaining requests. Required: 1, Available: 0",
    "details": {
      "limit": 50,
      "used": 50,
      "reset_date": "2026-07-01T00:00:00.000Z"
    },
    "suggested_action": "Please upgrade to a premium plan to continue using the API."
  }
}

تستخدم الخطط المدفوعة بنية الاستجابة نفسها، مع حدود وتواريخ إعادة ضبط وإرشادات ترقية خاصة بكل خطة.

تغيّرت الحصة أثناء المعالجة — 400 Bad Request​

يتم التحقق من الحصة قبل التنبؤ ويُخصم الاستخدام بعد نجاح المعالجة. إذا استهلك طلب متزامن آخر الحصة المتبقية بين العمليتين، فقد يعيد الخصم ما يلي:

{
  "error": "Insufficient remaining requests. Required: 1, Available: 0"
}

فشلت المعالجة — 500 Internal Server Error​

{
  "error": "Image age prediction failed"
}

إذا أعادت خدمة التنبؤ السابقة خطأً داخليًا أكثر تحديدًا، فقد تظهر رسالته في الحقل error ضمن البنية نفسها.

ملاحظات​

  • أرسل صورة واحدة فقط باستخدام حقل multipart المسمى file.
  • لا يُخصم الطلب إلا بعد أن تعيد خدمة التوقع نتيجة ناجحة.
  • قد تكون age قيمة عشرية؛ أما probability فنسبة مئوية صحيحة وليست قيمة عشرية بين 0 و1.
  • تعكس probability الثقة في تصنيف الجنس، لا في تقدير العمر؛ ولا توجد درجة ثقة مخصصة للعمر.
  • تعني مصفوفة detections الفارغة أن الطلب نجح، وليست خطأ.
  • التوقعات تقديرات من النموذج ولا ينبغي اعتبارها سمات هوية مؤكدة.