الانتقال إلى المحتوى الرئيسي
ستقدم هذه الوثيقة شرحًا لواجهة برمجة التطبيقات لتحديد ملامح الوجه، والتي يمكنها من خلال إدخال صورة تحديد ملامح الوجه (المعروفة أيضًا بتحديد نقاط الوجه الرئيسية)، وحساب 90 نقطة تشكل ملامح الوجه، بما في ذلك الحواجب (8 نقاط لكل جانب)، العيون (8 نقاط لكل جانب)، الأنف (13 نقطة)، الفم (22 نقطة)، شكل الوجه (21 نقطة)، بؤبؤ العين [أو الحدقة] (نقطتان).

​
عملية التقديم

لاستخدام واجهة برمجة التطبيقات، يجب أولاً الذهاب إلى صفحة واجهة برمجة التطبيقات لتحديد ملامح الوجه للتقدم للحصول على الخدمة المناسبة، بعد الدخول إلى الصفحة، انقر على زر “Acquire” كما هو موضح في الصورة: إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، بعد تسجيل الدخول أو التسجيل، سيتم العودة تلقائيًا إلى الصفحة الحالية. عند التقديم لأول مرة، سيكون هناك حد مجاني متاح، يمكنك استخدام واجهة برمجة التطبيقات مجانًا.

​
الاستخدام الأساسي

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال رابط الصورة، للحصول على صورة النتائج المعالجة، يجب أولاً تمرير حقل image_url، صورة الوجه كما هو موضح في الصورة أدناه:

يمكننا بعد ذلك ملء المحتوى المقابل في الواجهة، كما هو موضح في الصورة:

يمكنك أن ترى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح واجهة برمجة التطبيقات، بعد التقديم يمكنك اختياره مباشرة من القائمة المنسدلة.
بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:
  • image_url: رابط صورة الوجه التي تحتاج إلى معالجتها.
  • mode: وضع الكشف. 0 للكشف عن جميع الوجوه الموجودة، 1 للكشف عن أكبر وجه. الافتراضي هو 0.
  • face_model_version: إصدار نموذج الخوارزمية المستخدم في خدمة التعرف على الوجه، الافتراضي هو 3.0.
  • need_rotate_detection: ما إذا كان يجب تمكين دعم كشف دوران الصورة. 0 للإيقاف، 1 للتشغيل. الافتراضي هو 0.
بعد الاختيار، يمكنك أن تلاحظ أنه تم إنشاء كود مطابق على الجانب الأيمن، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء الاختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتائج التالية: 
{
  "image_width": 690,
  "image_height": 920,
  "face_model_version": "3.0",
  "face_shape_set": [
    {
      "face_profile": [
        {
          "x": 294,
          "y": 207
        },
        {
          "x": 289,
          "y": 216
        },
        {
          "x": 286,
          "y": 226
        },
        {
          "x": 284,
          "y": 236
        },
        {
          "x": 283,
          "y": 246
        },
        {
          "x": 283,
          "y": 256
        },
        {
          "x": 284,
          "y": 266
        },
        {
          "x": 286,
          "y": 276
        },
        {
          "x": 289,
          "y": 285
        },
        {
          "x": 294,
          "y": 294
        },
        {
          "x": 301,
          "y": 301
        },
        {
          "x": 314,
          "y": 306
        },
        {
          "x": 327,
          "y": 307
        },
        {
          "x": 340,
          "y": 306
        },
        {
          "x": 353,
          "y": 302
        },
        {
          "x": 365,
          "y": 296
        },
        {
          "x": 374,
          "y": 287
        },
        {
          "x": 382,
          "y": 276
        },
        {
          "x": 387,
          "y": 264
        },
        {
          "x": 392,
          "y": 251
        },
        {
          "x": 396,
          "y": 238
        }
      ],
      "left_eye": [
        {
          "x": 298,
          "y": 208
        },
        {
          "x": 301,
          "y": 212
        },
        {
          "x": 305,
          "y": 214
        },
        {
          "x": 309,
          "y": 215
        },
        {
          "x": 314,
          "y": 216
        },
        {
          "x": 313,
          "y": 210
        },
        {
          "x": 309,
          "y": 207
        },
        {
          "x": 303,
          "y": 206
        }
      ],
      "right_eye": [
        {
          "x": 363,
          "y": 229
        },
        {
          "x": 358,
          "y": 230
        },
        {
          "x": 353,
          "y": 229
        },
        {
          "x": 347,
          "y": 227
        },
        {
          "x": 342,
          "y": 224
        },
        {
          "x": 348,
          "y": 221
        },
        {
          "x": 354,
          "y": 221
        },
        {
          "x": 360,
          "y": 223
        }
      ],
      "left_eye_brow": [
        {
          "x": 296,
          "y": 196
        },
        {
          "x": 302,
          "y": 197
        },
        {
          "x": 308,
          "y": 198
        },
        {
          "x": 313,
          "y": 200
        },
        {
          "x": 319,
          "y": 202
        },
        {
          "x": 315,
          "y": 195
        },
        {
          "x": 309,
          "y": 192
        },
        {
          "x": 302,
          "y": 192
        }
      ],
      "right_eye_brow": [
        {
          "x": 377,
          "y": 221
        },
        {
          "x": 369,
          "y": 217
        },
        {
          "x": 360,
          "y": 213
        },
        {
          "x": 350,
          "y": 211
        },
        {
          "x": 341,
          "y": 208
        },
        {
          "x": 351,
          "y": 204
        },
        {
          "x": 362,
          "y": 206
        },
        {
          "x": 372,
          "y": 211
        }
      ],
      "mouth": [
        {
          "x": 296,
          "y": 262
        },
        {
          "x": 297,
          "y": 269
        },
        {
          "x": 299,
          "y": 276
        },
        {
          "x": 305,
          "y": 281
        },
        {
          "x": 315,
          "y": 283
        },
        {
          "x": 326,
          "y": 282
        },
        {
          "x": 335,
          "y": 277
        },
        {
          "x": 325,
          "y": 269
        },
        {
          "x": 315,
          "y": 262
        },
        {
          "x": 309,
          "y": 261
        },
        {
          "x": 305,
          "y": 258
        },
        {
          "x": 300,
          "y": 259
        },
        {
          "x": 299,
          "y": 265
        },
        {
          "x": 303,
          "y": 269
        },
        {
          "x": 307,
          "y": 272
        },
        {
          "x": 316,
          "y": 275
        },
        {
          "x": 325,
          "y": 276
        },
        {
          "x": 326,
          "y": 272
        },
        {
          "x": 317,
          "y": 269
        },
        {
          "x": 308,
          "y": 265
        },
        {
          "x": 304,
          "y": 263
        },
        {
          "x": 300,
          "y": 262
        }
      ],
      "nose": [
        {
          "x": 311,
          "y": 242
        },
        {
          "x": 325,
          "y": 220
        },
        {
          "x": 319,
          "y": 226
        },
        {
          "x": 313,
          "y": 231
        },
        {
          "x": 307,
          "y": 236
        },
        {
          "x": 302,
          "y": 243
        },
        {
          "x": 306,
          "y": 249
        },
        {
          "x": 311,
          "y": 252
        },
        {
          "x": 318,
          "y": 254
        },
        {
          "x": 329,
          "y": 253
        },
        {
          "x": 327,
          "y": 243
        },
        {
          "x": 326,
          "y": 235
        },
        {
          "x": 326,
          "y": 228
        }
      ],
      "left_pupil": [
        {
          "x": 310,
          "y": 211
        }
      ],
      "right_pupil": [
        {
          "x": 357,
          "y": 225
        }
      ]
    }
  ]
}
يمكن رؤية أنه في هذه اللحظة حصلنا على معلومات متعلقة بوجه الشخص في الصورة، بما في ذلك معلومات تحديد ملامح الوجه (نقاط الوجه الرئيسية) وإصدار نموذج الخوارزمية المستخدمة في التعرف على الوجه. تفسير الحقول كما يلي:
  • image_width ：عرض الصورة المطلوب.
  • image_height ：ارتفاع الصورة المطلوب.
  • face_model_version：إصدار نموذج الخوارزمية المستخدم في التعرف على الوجه.
  • face_shape_set：معلومات محددة عن تحديد ملامح الوجه (نقاط الوجه الرئيسية).
    • face_profile ：وصف 21 نقطة لملف شكل الوجه.
      • x ：إحداثيات x
      • y ：إحداثيات y
    • left_eye ：وصف 8 نقاط لملف شكل العين اليسرى.
      • x ：إحداثيات x
      • y ：إحداثيات y
    • right_eye ：وصف 8 نقاط لملف شكل العين اليمنى.
      • x ：إحداثيات x
      • y ：إحداثيات y
    • left_eye_brow ：وصف 8 نقاط لملف شكل الحاجب الأيسر.
      • x ：إحداثيات x
      • y ：إحداثيات y
    • right_eye_brow ：وصف 8 نقاط لملف شكل الحاجب الأيمن.
      • x ：إحداثيات x
      • y ：إحداثيات y
    • mouth ：وصف 22 نقطة لملف شكل الفم.
      • x ：إحداثيات x
      • y ：إحداثيات y
    • nose ：وصف 13 نقطة لملف شكل الأنف.
      • x ：إحداثيات x
      • y ：إحداثيات y
    • left_pupil ：نقطة واحدة لملف شكل بؤبؤ العين الأيسر.
      • x ：إحداثيات x
      • y ：إحداثيات y
    • right_pupil ：نقطة واحدة لملف شكل بؤبؤ العين الأيمن.
      • x ：إحداثيات x
      • y ：إحداثيات y
بالإضافة إلى ذلك، إذا كنت ترغب في توليد الكود المقابل، يمكنك نسخه مباشرة، على سبيل المثال، كود CURL كما يلي: 
curl -X POST 'https://api.acedata.cloud/face/analyze' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "image_url": "https://cdn.acedata.cloud/lrbtcn.jpg"
}'
كود التوصيل بلغة Python كما يلي: 
import requests

url = "https://api.acedata.cloud/face/analyze"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "image_url": "https://cdn.acedata.cloud/lrbtcn.jpg"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

​
معالجة الأخطاء

عند استدعاء API، إذا واجهت خطأ، ستقوم API بإرجاع رمز الخطأ والمعلومات ذات الصلة. على سبيل المثال:
  • 400 token_mismatched：طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 400 api_not_implemented：طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 401 invalid_token：غير مصرح، رمز التفويض غير صالح أو مفقود.
  • 429 too_many_requests：طلبات كثيرة جداً، لقد تجاوزت الحد الأقصى للطلبات.
  • 500 api_error：خطأ في الخادم الداخلي، حدث خطأ ما في الخادم.

​
مثال على استجابة الخطأ

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
الخاتمة

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