واجهة البحث بالوجه لوكلاء الذكاء الاصطناعي (x402)

أصبح بإمكان وكلاء الذكاء الاصطناعي عبر FaceCheck البحث عن أي وجه على الإنترنت باستخدام بروتوكول x402.

يقوم الوكيل بإرسال صورة الوجه ودفع تكلفة البحث بـ USDC على شبكة Solana، فيستلم في المقابل صفحات الويب المطابقة والصور المصغّرة ودرجات الثقة — دون الحاجة إلى حساب أو تسجيل أو مفتاح API أو رصيد مدفوع مسبقًا.

ما هو x402؟

x402 هو بروتوكول دفع مخصص لواجهات الـ API.

يتيح لوكيل الذكاء الاصطناعي معرفة سعر طلب الـ API، وتسديد قيمته، واستلام النتيجة عبر طلب HTTP عادي — مستفيدًا من رمز الحالة HTTP 402 Payment Required الذي ظل محجوزًا لهذا الغرض منذ زمن طويل.

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

ماذا يمكن للوكلاء أن يفعلوا بذلك؟

عبر نقطة النهاية x402 في FaceCheck، يستطيع وكلاء الذكاء الاصطناعي:

• البحث عن الوجوه المطابقة على الإنترنت
• إيجاد الصفحات التي يظهر فيها الوجه
• الحصول على روابط النتائج المطابقة
• استلام صور مصغّرة بصيغة base64
• الحصول على درجات الثقة

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

https://facecheck.id/x402/reverse-face-search

كيف يعمل؟

الأسعار

تأتي تكلفة البحث عبر نقطة x402 أعلى قليلًا من تكلفته عبر واجهة REST العادية، لأنها تشمل معالجة الدفع على السلسلة (on-chain) ولا تتطلّب أي إعداد لحساب.

السعر الحالي يظهر دائمًا في استجابة 402 Payment Required قبل أن يقوم الوكيل بأي دفع.

استجابة 402 هذه هي المرجع الرسمي للسعر.

مثال على تدفّق HTTP

يتكوّن تدفّق HTTP الخام من ثلاث خطوات: معرفة السعر، توقيع الدفع، ثم إرسال الصورة.

1. معرفة السعر

curl https://facecheck.id/x402/reverse-face-search

# الاستجابة:
# HTTP 402 Payment Required
# تتضمّن السعر، وعنوان استلام الدفع، وتفاصيل الطلب

2. توقيع الدفع

يوقّع الوكيل عملية الدفع باستخدام زوج مفاتيحه على Solana. في بيئة الإنتاج، عادةً ما تتكفّل بهذه الخطوة مكتبة عميل x402.

3. إرسال الصورة

curl -X POST https://facecheck.id/x402/reverse-face-search \
  -H "X-PAYMENT: <دفعة موقَّعة مُرمّزة بـ base64>" \
  -F "images=@daniel.jpg"

# الاستجابة:
# نتائج البحث بصيغة JSON
# لا تُسوَّى الدفعة فعليًا إلا عند إيجاد نتائج

تنسيق الاستجابة

ترجع عملية البحث الناجحة بـ JSON يحتوي على قائمة بالنتائج المطابقة:

{
  "match_count": 3,
  "took_ms": 4127,
  "matches": [
    {
      "url": "https://example.com/page-where-face-appears",
      "score": 92,
      "thumb_base64": "iVBORw0KGgoAAAANS..."
    }
  ]
}

تتضمّن كل نتيجة رابط المصدر، ودرجة الثقة، وصورة مصغّرة للوجه المطابق بصيغة base64.

استخدام مكتبة عميل

في الواقع العملي، يُفضَّل استخدام مكتبة عميل x402 تتولّى التدفّق بالكامل تلقائيًا:

1. الاستعلام عن السعر
2. توقيع الدفع
3. إعادة إرسال الطلب مع إرفاق الدفع
4. استلام نتائج البحث

مثال باستخدام x402-solana:

"""
Search the internet by face via FaceCheck's x402 endpoint.
Pays per call in USDC on Solana — no account, no API key.

Setup:
    pip install requests "x402[svm]"
    export SOLANA_KEYPAIR=<your base58 Solana secret key>
"""

import base64
import os
import requests
from x402 import x402ClientSync, parse_payment_required
from x402.mechanisms.svm import KeypairSigner
from x402.mechanisms.svm.exact.register import register_exact_svm_client

URL = "https://facecheck.id/x402/reverse-face-search"
IMAGE = "face.jpg"

# Set up the x402 client with your Solana wallet
client = x402ClientSync()
signer = KeypairSigner.from_base58(os.environ["SOLANA_KEYPAIR"])
register_exact_svm_client(client, signer)

# Step 1: GET the endpoint to discover price and payment destination.
payment_required = parse_payment_required(requests.get(URL).json())

# Step 2: Sign a USDC transfer authorization with your Solana keypair.
payload = client.create_payment_payload(payment_required)
payment_header = base64.b64encode(
    payload.model_dump_json(by_alias=True).encode()
).decode()

# Step 3: POST the image with the signed payment attached. The server
# verifies, runs the search, and only settles on-chain if results are found.
image = open(IMAGE, "rb").read()
r = requests.post(URL, data=image, headers={
    "Content-Type": "image/jpeg",
    "PAYMENT-SIGNATURE": payment_header,
})
result = r.json()

# Step 4: Iterate the matches (each has a base64-encoded thumbnail)
print(f"found {result['match_count']} matches in {result['took_ms']}ms")
for m in result["matches"]:
    thumb = m["thumb_base64"][:30]
    print(f"  score={m['score']}  thumb={thumb}...  {m['url']}")

/**
 * Search the internet by face via FaceCheck's x402 endpoint.
 * Pays per call in USDC on Solana — no account, no API key.
 *
 * Setup:
 *   npm install x402-solana @solana/web3.js bs58
 *   export SOLANA_KEYPAIR=<your base58 Solana secret key>
 *
 * Run:
 *   npx tsx test_client_minimal.ts
 */

import { createX402Client } from 'x402-solana/client';
import { Keypair, Transaction, VersionedTransaction } from '@solana/web3.js';
import bs58 from 'bs58';
import { readFileSync } from 'fs';

const URL = 'https://facecheck.id/x402/reverse-face-search';
const IMAGE = 'face.jpg';

async function main() {
  // Wrap a Node-side keypair in the WalletAdapter shape x402-solana expects
  const keypair = Keypair.fromSecretKey(bs58.decode(process.env.SOLANA_KEYPAIR!));
  const wallet = {
    publicKey: keypair.publicKey,
    signTransaction: async <T extends Transaction | VersionedTransaction>(tx: T): Promise<T> => {
      if (tx instanceof VersionedTransaction) tx.sign([keypair]);
      else tx.partialSign(keypair);
      return tx;
    },
  };

  // x402 client auto-handles the 402 → sign → retry flow
  const client = createX402Client({
    wallet,
    network: 'solana',                    // mainnet
    maxPaymentAmount: BigInt(5_000_000),  // safety cap: max $5.00 USDC per call
  });

  // POST the image; client handles payment transparently
  const response = await client.fetch(URL, {
    method: 'POST',
    headers: { 'Content-Type': 'image/jpeg' },
    body: readFileSync(IMAGE),
  });

  const result = await response.json();

  console.log(`found ${result.match_count} matches in ${result.took_ms}ms`);
  for (const m of result.matches) {
    console.log(`  score=${m.score}  thumb=${m.thumb_base64.slice(0, 30)}...  ${m.url}`);
  }
}

main().catch(console.error);

قد تختلف مكتبات العميل فيما بينها. راجع توثيق مكتبة x402 التي اخترتها للاطلاع على أحدث أسماء الدوال وطرق الاستخدام.

أطر عمل الوكلاء المتوافقة

تعمل نقطة النهاية x402 مع أي وكيل ذكاء اصطناعي أو نظام سير عمل قادر على إرسال طلبات HTTP وتوقيع معاملات Solana.

من أبرز الخيارات الشائعة:

• LangChain — تدفّقات عمل للوكلاء بلغة Python أو JavaScript
• CrewAI — تنسيق المهام بين عدة وكلاء
• Microsoft AutoGen — محادثات وتدفّقات عمل متعددة الوكلاء
• Claude MCP — استدعاء الأدوات عبر بروتوكول Model Context Protocol
• Coinbase AgentKit — أدوات وكلاء مصمّمة للدفع بالعملات الرقمية
• AutoGPT و Dify و n8n — منصّات بناء وكلاء بأسلوب سير العمل

إطار عمل الوكيل هو من يقرّر متى يستخدم أداة البحث بالوجه، بينما يتكفّل عميل x402 بمعرفة السعر وتوقيع الدفع وإعادة إرسال الطلب.

مقارنة بين x402 وواجهة REST

تدعم FaceCheck.ID كلًا من واجهة REST وبروتوكول x402.

متى تستخدم x402؟

استخدم نقطة النهاية x402 إذا كنت تريد:

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

استخدم واجهة REST إذا كنت تريد:

• مفتاح API تقليدي
• استخدام رصيد مدفوع مسبقًا
• تكاملات تطبيقات يمكن التنبّؤ بها
• استخدامًا على الخوادم الخلفية
• تكاملات بحجم أكبر أو طويلة الأمد

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

هل يمكن تجربة نقطة النهاية x402 مجانًا؟

لا. كل عملية بحث ناجحة تُدفع بـ USDC على Solana. يظهر السعر في استجابة 402 Payment Required قبل الدفع، فيعرف الوكيل التكلفة سلفًا دائمًا.

ماذا يحدث إذا لم يُعثر على أي تطابق؟

لن يُحتسب عليك أي مبلغ. لا تُسوَّى الدفعة على السلسلة إلا إذا أعاد البحث نتائج.

هل أحتاج إلى محفظة Solana؟

نعم. يحتاج الوكيل إلى زوج مفاتيح Solana مع رصيد USDC لتوقيع الدفع. لا حاجة لحساب FaceCheck.

لماذا USDC بدلًا من العملات التقليدية؟

تُسوَّى عملات USDC على Solana خلال ثوانٍ وبرسوم منخفضة جدًا، وهو ما يجعلها عمليًا الخيار الواقعي لوكلاء يدفعون مقابل كل استدعاء API دون أي تدخّل بشري.

هل يمكنني استخدام x402 من تطبيق عادي بدل وكيل ذكاء اصطناعي؟

نعم، يمكنك ذلك، لكن واجهة REST عادةً ما تكون أنسب للتطبيقات والخوادم التقليدية. أما x402 فهو مُحسَّن للاستخدام المستقل والدفع عند كل استدعاء.

هل يعمل x402 مع Claude أو ChatGPT أو غيرهما من وكلاء النماذج اللغوية الكبيرة؟

أي إطار وكيل قادر على إرسال طلبات HTTP وتوقيع معاملة Solana يمكنه استخدام نقطة النهاية — بما في ذلك إعدادات استدعاء الأدوات عبر Claude MCP و LangChain و CrewAI و AutoGen وغيرها. راجع قسم «أطر عمل الوكلاء المتوافقة» أعلاه.

قراءات إضافية

• توثيق واجهة REST في FaceCheck
• مواصفات Swagger
• نصائح للبحث العكسي بالوجه عبر الصور
• نظرة عامة على بروتوكول x402
• USDC على Solana

تخضع جميع عمليات البحث في FaceCheck لـشروط الاستخدام.