الفرق بين JSON API وForm API في CaptchaAI وأيهما تختار

النتيجة واحدة أياً كان التنسيق: يعالج خادم CaptchaAI الترميز بالنموذج وجسم JSON بالطريقة نفسها، فلا فرق في سرعة الحل ولا في دقته. الفرق الحقيقي ينحصر في راحة الكتابة وسهولة صيانة الكود داخل مشروعك.

القاعدة السريعة قبل الدخول في التفاصيل:

• تهاجر من 2Captcha أو Anti-Captcha؟ ابقَ على الترميز بالنموذج — التنسيق نفسه، ولن تحتاج إلى تعديل منطق الطلبات.
• تبني تكاملاً حديثاً بأسلوب REST أو تعمل بـ TypeScript؟ اختر JSON ليتناسق مع بقية خدماتك.
• ترسل صوراً كبيرة أو ملفات؟ التفصيل في الأسفل يحسم الاختيار لكل حالة على حدة.

بقية المقالة تشرح كل نقطة بمثال جاهز، وتنتهي بجدول قرار يوضح متى تختار كل تنسيق.

طريقتان لإرسال الطلب نفسه

كلا الأسلوبين يصل إلى نقطة النهاية ذاتها ويحمل الحقول نفسها؛ ما يتغير هو ترويسة Content-Type وشكل الحمولة.

الترميز بالنموذج — الأسلوب الافتراضي

import requests

resp = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": "SITE_KEY",
    "pageurl": "https://example.com",
    "json": 1,
})

نوع المحتوى هنا: application/x-www-form-urlencoded

جسم JSON

import requests

resp = requests.post("https://ocr.captchaai.com/in.php", json={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": "SITE_KEY",
    "pageurl": "https://example.com",
    "json": 1,
})

نوع المحتوى هنا: application/json

لاحظ أن الفرق الوحيد في Python هو الكلمة المفتاحية: data= للنموذج مقابل json= لجسم JSON.

اضمن استجابة JSON دائماً عبر json=1

بمعزل عن تنسيق الطلب، تحصل على استجابة بصيغة JSON بمجرد إضافة الحقل json=1. من دونه يعود الرد نصاً عادياً يجب تحليله يدوياً:

# Without json=1 — plain text response
resp = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": "SITE_KEY",
    "pageurl": "https://example.com",
})
# Response: "OK|12345678"

# With json=1 — JSON response
resp = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": "SITE_KEY",
    "pageurl": "https://example.com",
    "json": 1,
})
# Response: {"status": 1, "request": "12345678"}

القاعدة الذهبية: أضف json=1 دائماً حتى يكون التحليل موحّداً وسهلاً في كل استجابة.

أبرز الفروق بين التنسيقين

بعد أن رأيت الطلب في الحالتين، يلخّص الجدول التالي ما يتغير فعلياً عند الانتقال من تنسيق إلى آخر:

طالما بياناتك حقول بسيطة، لن تلمس فرقاً يُذكر بين التنسيقين؛ ويبدأ JSON بالتفوّق حين تصبح البنية متداخلة أو تحتوي على مصفوفات.

أمثلة عملية بلغة Python

المثالان التاليان يغطيان دورة كاملة: إرسال المهمة ثم استطلاع النتيجة. لاحظ أن الاستطلاع يجري دائماً عبر GET مع معلمات الاستعلام مهما كان تنسيق الإرسال.

الترميز بالنموذج

import requests

# Submit
resp = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": "SITE_KEY",
    "pageurl": "https://example.com",
    "json": 1,
})
task_id = resp.json()["request"]

# Poll (always GET with query params)
resp = requests.get("https://ocr.captchaai.com/res.php", params={
    "key": "YOUR_API_KEY",
    "action": "get",
    "id": task_id,
    "json": 1,
})

جسم JSON

import requests

# Submit with JSON
resp = requests.post("https://ocr.captchaai.com/in.php", json={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": "SITE_KEY",
    "pageurl": "https://example.com",
    "json": 1,
})
task_id = resp.json()["request"]

# Poll (same as form-encoded — GET with params)
resp = requests.get("https://ocr.captchaai.com/res.php", params={
    "key": "YOUR_API_KEY",
    "action": "get",
    "id": task_id,
    "json": 1,
})

خطوة الإرسال هي وحدها التي تتغير؛ أما استطلاع /res.php فيبقى واحداً في الحالتين.

أمثلة عملية بلغة Node.js

في Node.js يظهر الفرق أوضح: النموذج يحتاج إلى تحويل الحقول بـ qs.stringify، بينما JSON يمرّر الكائن كما هو ويضبط Axios الترويسة تلقائياً.

الترميز بالنموذج

const axios = require('axios');
const qs = require('querystring');

// Submit
const resp = await axios.post(
  'https://ocr.captchaai.com/in.php',
  qs.stringify({
    key: 'YOUR_API_KEY',
    method: 'userrecaptcha',
    googlekey: 'SITE_KEY',
    pageurl: 'https://example.com',
    json: 1,
  })
);
const taskId = resp.data.request;

جسم JSON

const axios = require('axios');

// Submit with JSON
const resp = await axios.post(
  'https://ocr.captchaai.com/in.php',
  {
    key: 'YOUR_API_KEY',
    method: 'userrecaptcha',
    googlekey: 'SITE_KEY',
    pageurl: 'https://example.com',
    json: 1,
  }
);
const taskId = resp.data.request;

اختبارات CAPTCHA الصورية: هنا يصبح التنسيق حاسماً

مع اختبارات الصور يتوقف الأمر على طريقة نقل البيانات الثنائية، فلكل مسار عيوبه ومزاياه. أمامك ثلاثة مسارات، بالترتيب نفسه الذي ستقابله عند التطبيق:

1. رفع الملف مباشرة عبر النموذج بأسلوب Multipart.
2. ترميز الصورة Base64 داخل جسم JSON.
3. ترميز الصورة Base64 داخل بيانات النموذج.

رفع الملف عبر النموذج — Multipart

# File upload — form-encoded with multipart
resp = requests.post("https://ocr.captchaai.com/in.php",
    data={
        "key": "YOUR_API_KEY",
        "method": "post",
        "json": 1,
    },
    files={
        "file": open("captcha.png", "rb"),
    },
)

JSON مع Base64

import base64

# Base64 in JSON body
with open("captcha.png", "rb") as f:
    body = base64.b64encode(f.read()).decode()

resp = requests.post("https://ocr.captchaai.com/in.php", json={
    "key": "YOUR_API_KEY",
    "method": "base64",
    "body": body,
    "json": 1,
})

النموذج مع Base64

# Base64 in form data
resp = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": "YOUR_API_KEY",
    "method": "base64",
    "body": body,
    "json": 1,
})

الفرق العملي: رفع الملف مباشرة عبر Multipart أخفّ على الذاكرة لأنه لا يضخّم حجم الصورة، بينما يزيد ترميز Base64 الحجم بنحو الثلث. لهذا يُفضّل النموذج مع الصور الكبيرة، ويبقى JSON مع Base64 أنسب حين تكون الصورة جزءاً من حمولة مركّبة.

دليل الاختيار حسب السيناريو

استخدم هذا الجدول كمرجع سريع عند بناء التكامل:

مثال من واقع فرق التطوير في المنطقة: فريق في القاهرة يدير خط أتمتة لجمع بيانات المنتجات كان يعتمد على 2Captcha، وقرّر الانتقال إلى CaptchaAI لخفض التكلفة الشهرية. ولأن الكود القائم يرسل الطلبات بالترميز بالنموذج، أبقى الفريق على التنسيق نفسه وغيّر عنوان نقطة النهاية ومفتاح الـ API فقط، فاكتمل الترحيل دون إعادة كتابة طبقة الشبكة. أما الخدمة الجديدة التي يبنيها الفريق ذاته بواجهة REST حديثة فبدأت مباشرة بـ JSON. ويُبنى تسعير CaptchaAI على عدد الـ threads المتزامنة لا على كل عملية حل، ما يجعل التكلفة الشهرية ثابتة ومتوقعة بصرف النظر عن التنسيق الذي ترسل به.

أخطاء شائعة وكيفية تجنّبها

معظم مشكلات التكامل الأولى تعود إلى واحدة من هذه النقاط الأربع:

• استخدام json={} دون تمرير json: 1 ضمن البيانات: تعود الاستجابة نصاً عادياً؛ الحل أن تضمّن "json": 1 صراحةً في البيانات.
• خلط data= وjson= في طلب Python واحد: يصبح الطلب غير صالح؛ استخدم أحد الأسلوبين فقط لا كليهما.
• نسيان ترويسة نوع المحتوى: يعجز الخادم عن تحليل الجسم؛ اترك مكتبة HTTP تضبط الترويسة تلقائياً.
• إرسال جسم JSON إلى نقطة الاستطلاع: الاستطلاع يعتمد على معلمات GET؛ استخدم دائماً GET مع معلمات الاستعلام لـ /res.php.

قبل نشر التكامل، راجع مرجع رموز أخطاء CaptchaAI لمطابقة أي رمز خطأ يعود إليك مع سببه الدقيق.

الأسئلة الشائعة

لماذا تعود الاستجابة نصاً مثل OK|12345678 بدل JSON؟

لأنك لم تُضِف json=1 إلى الطلب. الحقل هو ما يبدّل شكل الاستجابة، لا تنسيق الإرسال؛ أضِفه لتحصل دائماً على {"status": 1, "request": "..."} سهلة التحليل.

هل أضبط ترويسة Content-Type بنفسي؟

لا داعي في الغالب. تضبط مكتبات مثل requests وAxios الترويسة الصحيحة تلقائياً حسب ما إذا استخدمت data= أو json=. الضبط اليدوي يفيد فقط إذا كنت تبني الطلب بأداة منخفضة المستوى مثل cURL الخام.

أي تنسيق أستخدم لرفع صورة CAPTCHA كبيرة؟

فضّل الترميز بالنموذج، سواء عبر رفع الملف بـ Multipart أو بحقل Base64. فترميز Base64 يزيد الحجم المنقول، والنموذج يتعامل مع الحمولات الكبيرة بكفاءة أعلى من دفعها داخل جسم JSON.

أنتقل من 2Captcha؛ هل أغيّر تنسيق الطلبات؟

لا حاجة. واجهة 2Captcha الأصلية تعتمد الترميز بالنموذج، وCaptchaAI يضيف دعم JSON فوقه دون أن يلغيه. أبقِ كودك على النموذج، وغيّر مفتاح الـ API ونقطة النهاية فقط لإتمام الترحيل.

أدلة ذات صلة

• تأمين مفتاح الـ API والقائمة البيضاء لعناوين IP
• مرجع رموز أخطاء CaptchaAI وحلولها

اختر التنسيق الأنسب لمشروعك وابدأ مع CaptchaAI API اليوم.