YZ Ajanları için Yüzle Arama API’si (x402)

FaceCheck artık YZ ajanlarının internette yüzle arama yapmasına x402 protokolü üzerinden olanak tanıyor.

Ajan bir yüz fotoğrafı gönderir, aramanın bedelini Solana üzerinde USDC ile öder ve karşılığında eşleşen web sayfalarını, küçük resimleri ve eşleşme skorlarını alır — üstelik hesap, kayıt, API anahtarı veya ön ödemeli kredi gerekmeden.

x402 nedir?

x402, API’ler için bir ödeme protokolüdür.

YZ ajanının bir API isteğinin fiyatını öğrenmesine, ödemesini yapmasına ve sonucu sıradan bir HTTP isteğiyle almasına imkân tanır — uzun süredir bu iş için ayrılmış olan HTTP 402 Payment Required durum kodunu kullanarak.

FaceCheck için bu, ajanın açık internette tersine yüz araması yapabilmesi anlamına gelir; üstelik FaceCheck hesabına, API anahtarına ya da peşin alınmış kredilere ihtiyaç duymadan.

Ajanlar bununla neler yapabilir?

FaceCheck’in x402 uç noktasını kullanan YZ ajanları şunları yapabilir:

• internette eşleşen yüzleri aramak
• bir yüzün geçtiği web sayfalarını bulmak
• eşleşen URL’leri almak
• base64 biçiminde küçük resimleri almak
• eşleşme skorlarına ulaşmak

x402 uç noktası

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

Nasıl çalışır?

Ücretlendirme

x402 uç noktası, arama başına klasik REST API’den biraz daha pahalıdır; çünkü zincir üstü ödeme yönetimini kapsar ve hiç hesap kurulumu gerektirmez.

Güncel fiyat, ajan henüz ödeme yapmadan önce her zaman 402 Payment Required yanıtında belirtilir.

Fiyatın resmi kaynağı bu 402 yanıtıdır.

Örnek HTTP akışı

Ham HTTP akışı üç adımdan oluşur: fiyatı öğren, ödemeyi imzala, görseli gönder.

1. Fiyatı öğren

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

# Yanıt:
# HTTP 402 Payment Required
# Fiyatı, ödeme adresini ve isteğin ayrıntılarını içerir

2. Ödemeyi imzala

Ajan, ödemeyi kendi Solana anahtar çiftiyle imzalar. Üretim ortamında bu imzalama adımı genellikle bir x402 istemci kütüphanesine bırakılır.

3. Görseli gönder

curl -X POST https://facecheck.id/x402/reverse-face-search \
  -H "X-PAYMENT: <base64 ile kodlanmış imzalı ödeme>" \
  -F "images=@daniel.jpg"

# Yanıt:
# JSON biçiminde arama sonuçları
# Ödeme yalnızca sonuç döndüğünde gerçekten alınır

Yanıt biçimi

Başarılı bir arama, eşleşme listesini içeren bir JSON döndürür:

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

Her eşleşmede kaynak URL, eşleşme skoru ve bulunan yüzün base64 ile kodlanmış küçük resmi yer alır.

İstemci kütüphanesiyle kullanım

Uygulamada en kolayı, tüm akışı otomatik olarak yöneten bir x402 istemci kütüphanesi kullanmaktır:

1. fiyatı öğrenir
2. ödemeyi imzalar
3. isteği ödeme bilgisiyle birlikte yeniden gönderir
4. arama sonuçlarını alır

x402-solana ile örnek:

"""
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);

İstemci kütüphaneleri birbirinden farklı olabilir. Güncel metot adları ve kullanım için seçtiğiniz x402 kütüphanesinin belgelerine bakın.

Uyumlu ajan çatıları

x402 uç noktası, HTTP isteği gönderebilen ve Solana ödemelerini imzalayabilen her YZ ajanı veya iş akışı sistemiyle çalışır.

Sık tercih edilen seçenekler:

• LangChain — Python veya JavaScript ile ajan iş akışları
• CrewAI — çoklu ajan görev orkestrasyonu
• Microsoft AutoGen — çoklu ajan diyalogları ve iş akışları
• Claude MCP — Model Context Protocol üzerinden araç çağırma
• Coinbase AgentKit — kripto ödemeler için tasarlanmış ajan araç seti
• AutoGPT, Dify ve n8n — iş akışı tabanlı ajan oluşturucular

Yüzle arama aracının ne zaman kullanılacağına ajan çatısı karar verir. Fiyatın öğrenilmesi, imzalama ve isteğin yeniden gönderilmesi ise x402 istemcisinin işidir.

x402 ile REST API karşılaştırması

FaceCheck.ID hem REST API’yi hem de x402 protokolü’nü destekler.

x402’yi ne zaman kullanmalı?

x402 uç noktasını şu durumlarda tercih edin:

• açık internette tersine yüz araması yapan YZ ajanları kullanmak istediğinizde
• kayıt, API anahtarı veya ön ödemeli kredilere takılmak istemediğinizde
• kullandıkça öde modelini tercih ettiğinizde
• kendi araçlarının ücretini doğrudan ödeyen otonom ajanlar kullanmak istediğinizde
• ara sıra ya da tek seferlik yüz aramaları yapmanız gerektiğinde
• mümkün olan en yüksek arama önceliğini istediğinizde

REST API’yi şu durumlarda tercih edin:

• klasik bir API anahtarı kullanmak istediğinizde
• ön ödemeli kredilerle çalışmak istediğinizde
• öngörülebilir uygulama entegrasyonları kurduğunuzda
• arka uç sunucularından kullanmak istediğinizde
• daha yüksek hacimli veya uzun süreli entegrasyonlar yaptığınızda

Sıkça sorulan sorular

x402 uç noktasını ücretsiz deneyebilir miyim?

Hayır. Sonuç dönen her arama, Solana üzerinde USDC ile ödenir. Fiyat, ödeme yapılmadan önce 402 Payment Required yanıtında dönülür; böylece ajan, maliyeti her zaman önceden bilir.

Hiç eşleşme bulunmazsa ne olur?

Ücretlendirilmezsiniz. Zincir üstü ödeme, yalnızca arama sonuç döndüğünde gerçekten alınır.

Solana cüzdanına ihtiyacım var mı?

Evet. Ajan, ödemeleri imzalayabilmek için USDC bulunduran bir Solana anahtar çiftine ihtiyaç duyar. FaceCheck hesabı ise gerekmez.

Neden klasik para yerine USDC?

Solana üzerindeki USDC transferleri saniyeler içinde ve çok düşük ücretlerle tamamlanır; işte bu, ajanların her API çağrısı için insan müdahalesine gerek kalmadan ödeme yapmasını gerçekten pratik hale getirir.

x402’yi YZ ajanı yerine sıradan bir uygulamadan kullanabilir miyim?

Kullanabilirsiniz; ancak klasik uygulamalar ve arka uçlar için genellikle REST API daha uygundur. x402, otonom ve “çağrı başına ödeme” kullanımına göre optimize edilmiştir.

x402, Claude, ChatGPT veya başka LLM ajanlarıyla çalışır mı?

HTTP isteği gönderebilen ve Solana işlemini imzalayabilen herhangi bir ajan çatısı bu uç noktayı kullanabilir — bunlara Claude MCP, LangChain, CrewAI, AutoGen ve diğerleri aracılığıyla yapılan araç çağırma yapılandırmaları da dahildir. Yukarıdaki “Uyumlu ajan çatıları” bölümüne bakın.

Daha fazlası

• FaceCheck REST API belgeleri
• Swagger spesifikasyonu
• Görselden tersine yüz arama ipuçları
• x402 protokolüne genel bakış
• Solana üzerinde USDC

Tüm FaceCheck aramaları kullanım koşullarına tabidir.