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

API تحديد الجنس من الصورة

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

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

https://api.genderrecognition.com

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

POST /v1/image-gender/api

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

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" \
  -H "apiKey: YOUR_API_KEY" \
  -F "file=@people.jpg"

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

{
  "success": true,
  "detections": [
    {
      "category": "face",
      "gender": "female",
      "probability": 99
    },
    {
      "category": "person",
      "gender": "male",
      "probability": 94
    }
  ],
  "remainingRequests": 2999
}

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

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

عندما ينتمي الوجه والجسم إلى الشخص نفسه، تتضمن الاستجابة نتيجة face واحدة بدلًا من نتيجتين منفصلتين للوجه والشخص.

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

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

{
  "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 gender prediction failed"
}

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

ملاحظات​

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