hCaptcha واجهة برمجة التطبيقات للتعرف على الصور

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

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

لاستخدام واجهة برمجة التطبيقات للتعرف على الصور hCaptcha، يجب أولاً الذهاب إلى وحدة التحكم في Ace Data Cloud للحصول على رمز API الخاص بك، احتفظ به للاستخدام لاحقًا.

إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد الانتهاء، سيتم إرجاعك تلقائيًا إلى الصفحة الحالية. يمكن استخدام رمز API واحد لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة. عند التقديم لأول مرة، ستحصل على رصيد مجاني لتجربته؛ وعند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في وحدة التحكم.

📘 الوثائق الكاملة: واجهة برمجة التطبيقات للتعرف على الصور hCaptcha →

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

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال صورة التحقق من hCaptcha التي تحتاج إلى معالجتها، للحصول على النتيجة المعالجة. يجب أولاً تمرير حقل queries، وهو صورة التحقق من hCaptcha المحددة، نحتاج إلى التقاط صورة لهذه الصورة من موقع يحتوي على تحقق hCaptcha، ورابط الموقع التجريبي هو: https://democaptcha.com/demo-form-eng/hcaptcha.html، انقر على مربع الاختيار لعرض صورة التحقق الكاملة، كما هو موضح في الصورة أدناه:

حيث أن حقل queries هو لقطة الشاشة لصورة التحقق المذكورة أعلاه، يُفضل ألا يتجاوز حجم الصورة 100 كيلوبايت، ويجب أيضًا التقاط لقطة للمنطقة المشار إليها بالسهم الأحمر في الصورة أعلاه، ويجب عليك ضغط حجم الصورة بنفسك، وتحويلها إلى ترميز Base64، كما هو موضح في الصورة أدناه:

كما يجب إدخال معلمة المحتوى المتعلق بصورة التحقق question، والتي تدعم الترجمة بين الصينية والإنجليزية، يمكنك إدخال المحتوى المتعلق بالتعرف مباشرة. من المحتوى المنفذ في الصورة أعلاه، يمكن أن نرى أن إدخال question يجب أن يكون Please click on the UNIQUE object among the others.. المحتوى المحدد كما يلي:

يمكننا أن نرى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:

accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
authorization: مفتاح استدعاء واجهة برمجة التطبيقات، يمكنك اختياره مباشرة بعد التقديم.

بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:

queries: قائمة صور التحقق المشفرة بتنسيق Base64.
question: معلمة المحتوى المتعلق بصورة التحقق، تدعم الإدخال المباشر باللغتين الصينية والإنجليزية.

بعد الاختيار، يمكنك أن تلاحظ أنه تم إنشاء كود مطابق على الجانب الأيمن، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء الاختبار، كما هو موضح في الصورة أعلاه، وهنا حصلنا على النتيجة التالية:

{
  "solution": {
    "label": "Please click on the UNIQUE object among the others",
    "box": [
      "360",
      "276"
    ],
    "confidences": 0.6354503631591797
  }
}

تتضمن النتيجة عدة حقول، كما يلي:

solution، نتيجة التحقق من معالجة صورة التحقق hCaptcha.
- label، المحتوى الذي تم التعرف عليه من صورة التحقق hCaptcha.
- box، معلومات موقع نتيجة التعرف على صورة التحقق hCaptcha، وهي تتكون من معلومات إحداثيات الصورة.
- confidences، مستوى الثقة في التعرف على المحتوى بعد معالجة صورة التحقق hCaptcha.

يمكننا أن نرى أننا حصلنا على نتيجة التحقق من معالجة صورة التحقق hCaptcha، كل ما علينا فعله هو محاكاة النقر على منطقة الصورة بناءً على معلومات إحداثيات box في النتيجة لتجاوز التحقق. سنستعرض الآن كيفية النقر بناءً على معلومات موقع box، أولاً، يجب إنشاء نظام إحداثيات قائم على الصورة المرفوعة، حيث تكون نقطة الأصل في الزاوية السفلية اليسرى للصورة، 360 هو الإحداثي الأفقي، و276 هو الإحداثي العمودي، كل ما علينا فعله هو محاكاة النقر على الإحداثيات المقابلة للصورة، كما هو موضح في الصورة أدناه:

إذا كنت ترغب في إنشاء كود التكامل المقابل، يمكنك نسخه مباشرة، على سبيل المثال، كود CURL كما يلي:

curl -X POST 'https://api.acedata.cloud/captcha/recognition/hcaptcha' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "question": "Please click on the UNIQUE object among the others.",
  "queries": ["iVBORw0KGgoAAAANSU.....eY+85KVlzKHav28uq/WLVhL2kHUlFMKUcZbL31S8bpd0pEPKxNllXAE2wgu3uEfj+BfAzOGelsQNFAAAAAElFTkSuQmCC"]
}'

كود التكامل بلغة بايثون كما يلي:

import requests

url = "https://api.acedata.cloud/captcha/recognition/hcaptcha"

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

payload = {
    "question": "Please click on the UNIQUE object among the others.",
    "queries": ["iVBORw0KGgoAAAANSU.....eY+85KVlzKHav28uq/WLVhL2kHUlFMKUcZbL31S8bpd0pEPKxNllXAE2wgu3uEfj+BfAzOGelsQNFAAAAAElFTkSuQmCC"]
}

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

الوضع غير المتزامن (async)

بشكل افتراضي، تكون واجهة برمجة التطبيقات متزامنة وتنتظر: ستظل الطلبات تنتظر حتى تكتمل معالجة نتائج التعرف قبل أن تعود. إذا كنت تقوم بتدوير عدة حلّات (multi-solver rotation) وترغب في “تقديم المهمة والحصول على task_id على الفور، ثم جدولة حلّات أخرى، والعودة لاحقًا للحصول على النتائج”، يمكنك تمرير async: true في جسم الطلب. بعد تمرير async: true، ستعيد الواجهة على الفور task_id، دون الانتظار:

curl -X POST 'https://api.acedata.cloud/captcha/recognition/hcaptcha' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "question": "Please click on the UNIQUE object among the others.",
  "queries": ["iVBORw0KGgoAAAANSU.....eY+85KVlzKHav28uq/WLVhL2kHUlFMKUcZbL31S8bpd0pEPKxNllXAE2wgu3uEfj+BfAzOGelsQNFAAAAAElFTkSuQmCC"],
  "async": true
}'

{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab",
  "status": "processing"
}

ثم استخدم task_id لاستطلاع POST /captcha/tasks (يوصى كل 3~5 ثوانٍ مرة واحدة) للحصول على النتائج:

curl -X POST 'https://api.acedata.cloud/captcha/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002"
}'

أثناء المعالجة، ستعود status: processing:

{ "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "processing" }

عند الانتهاء من المعالجة، ستعود status: ready ونتيجة التعرف solution (هيكل الحقول متطابق تمامًا مع وضع التزامن):

{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "ready",
  "solution": {
    "label": "يرجى النقر على الكائن الفريد بين الآخرين",
    "box": ["360", "276"],
    "confidences": 0.6354503631591797
  }
}

شرح الفوترة: في وضع غير المتزامن، لا يتم احتساب رسوم لإنشاء المهام واستطلاع “قيد المعالجة”؛ يتم احتساب الرسوم مرة واحدة فقط عند الحصول على نتيجة التعرف بنجاح (بأسعار متطابقة مع وضع التزامن). لذلك، فإن إلغاء المهام التي لم تكتمل بعد أثناء التبديل لن ينتج عنه أي رسوم. /captcha/tasks متاح لجميع واجهات التحقق من CAPTCHA (سلسلة التوكن والتعرف) ويمكن استخدام نفس task_id للاستطلاع.

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

عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستعيد واجهة برمجة التطبيقات رمز الخطأ والمعلومات المناسبة. على سبيل المثال:

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

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

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "فشل في الاسترجاع"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

الخاتمة

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

البداية

دردشة الذكاء الاصطناعي

صورة الذكاء الاصطناعي

فيديو الذكاء الاصطناعي

الصوت الذكي

الويب والبيانات

CAPTCHA

الهوية

وكيل

متقدم

hCaptcha واجهة برمجة التطبيقات للتعرف على الصور

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

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

الوضع غير المتزامن (async)

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

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

الخاتمة

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

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

​الوضع غير المتزامن (async)

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

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

​الخاتمة

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

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

الوضع غير المتزامن (async)

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

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

الخاتمة