> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

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

> hCaptcha verification code recognition service API guide - Ace Data Cloud

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

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

لاستخدام واجهة برمجة التطبيقات للتعرف على الصور hCaptcha، يجب أولاً الذهاب إلى [وحدة التحكم في Ace Data Cloud](https://platform.acedata.cloud/console/applications) للحصول على رمز API الخاص بك، احتفظ به للاستخدام لاحقًا.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

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

**يمكن استخدام رمز API واحد لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة.** عند التقديم لأول مرة، ستحصل على رصيد مجاني لتجربته؛ وعند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في [وحدة التحكم](https://platform.acedata.cloud/console/coin).

> 📘 الوثائق الكاملة: [واجهة برمجة التطبيقات للتعرف على الصور hCaptcha →](https://platform.acedata.cloud/documents/recognition-hcaptcha-integration)

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

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

<p>
  <img src="https://cdn.acedata.cloud/xryo59.png" width="500" className="m-auto" />
</p>

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

<p>
  <img src="https://cdn.acedata.cloud/g8ikkb.png" width="500" className="m-auto" />
</p>

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

<p>
  <img src="https://cdn.acedata.cloud/empncr.png" width="500" className="m-auto" />
</p>

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

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

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

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

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

<p>
  <img src="https://cdn.acedata.cloud/bww9b0.png" width="500" className="m-auto" />
</p>

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

```json theme={null}
{
  "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 هو الإحداثي العمودي، كل ما علينا فعله هو محاكاة النقر على الإحداثيات المقابلة للصورة، كما هو موضح في الصورة أدناه:

<p>
  <img src="https://cdn.acedata.cloud/4ykvbl.png" width="500" className="m-auto" />
</p>

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

```shell theme={null}
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"]
}'
```

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

```python theme={null}
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`، دون الانتظار:

```shell theme={null}
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
}'
```

```json theme={null}
{
  "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 ثوانٍ مرة واحدة) للحصول على النتائج:

```shell theme={null}
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`:

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

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

```json theme={null}
{
  "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`: خطأ في الخادم الداخلي، حدث خطأ ما على الخادم.

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

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

## الخاتمة

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