API wyszukiwania twarzy dla agentów AI (x402)

FaceCheck pozwala teraz agentom AI przeszukiwać internet po twarzy dzięki protokołowi x402.

Agent wysyła zdjęcie twarzy, płaci za wyszukiwanie w USDC na Solanie i w zamian dostaje pasujące strony, miniatury oraz wyniki dopasowania — bez konta, rejestracji, klucza API czy doładowanych wcześniej kredytów.

Czym jest x402?

x402 to protokół płatności dla API.

Pozwala agentowi AI sprawdzić cenę zapytania do API, opłacić je i odebrać wynik w jednym zwykłym żądaniu HTTP — w oparciu o zarezerwowany od dawna kod statusu HTTP 402 Payment Required.

W przypadku FaceCheck znaczy to tyle, że agent może wykonać odwrotne wyszukiwanie twarzy w otwartym internecie — bez konta w FaceCheck, bez klucza API i bez wcześniej zakupionych kredytów.

Co agenci mogą z tym zrobić?

Korzystając z endpointu x402 FaceCheck, agenci AI mogą:

• przeszukiwać internet w poszukiwaniu pasujących twarzy
• znajdować strony, na których pojawia się dana twarz
• pobierać adresy URL trafień
• otrzymywać miniatury zakodowane w base64
• dostawać wyniki dopasowania

Endpoint x402

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

Jak to działa

Cennik

Pojedyncze wyszukiwanie przez endpoint x402 kosztuje trochę więcej niż przez klasyczne API REST, bo obejmuje obsługę płatności on-chain i nie wymaga w ogóle zakładania konta.

Aktualna cena zawsze pojawia się w odpowiedzi 402 Payment Required, zanim agent w ogóle zapłaci.

To właśnie odpowiedź 402 jest oficjalnym źródłem informacji o cenie.

Przykładowy przebieg HTTP

Surowy przepływ HTTP składa się z trzech kroków: poznanie ceny, podpisanie płatności i wysłanie obrazu.

1. Poznaj cenę

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

# Odpowiedź:
# HTTP 402 Payment Required
# Zawiera cenę, adres odbiorcy płatności i szczegóły żądania

2. Podpisz płatność

Agent podpisuje płatność własną parą kluczy Solany. W środowisku produkcyjnym ten krok zazwyczaj wykonuje za nas biblioteka klienta x402.

3. Wyślij obraz

curl -X POST https://facecheck.id/x402/reverse-face-search \
  -H "X-PAYMENT: <podpisana płatność zakodowana w base64>" \
  -F "images=@daniel.jpg"

# Odpowiedź:
# Wyniki wyszukiwania w formacie JSON
# Płatność rozlicza się dopiero wtedy, gdy są jakieś trafienia

Format odpowiedzi

Udane wyszukiwanie zwraca JSON z listą trafień:

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

Każde trafienie zawiera adres URL źródła, wynik dopasowania oraz miniaturę znalezionej twarzy zakodowaną w base64.

Z użyciem biblioteki klienta

W praktyce najlepiej posłużyć się biblioteką klienta x402, która obsłuży cały przepływ automatycznie:

1. sprawdza cenę
2. podpisuje płatność
3. ponawia żądanie z dołączoną płatnością
4. odbiera wyniki wyszukiwania

Przykład z użyciem 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);

Biblioteki klienta mogą się różnić. Aktualne nazwy metod i sposób użycia znajdziesz w dokumentacji wybranej biblioteki x402.

Kompatybilne frameworki agentów

Endpoint x402 współpracuje z dowolnym agentem AI lub systemem workflow, który potrafi wysyłać żądania HTTP i podpisywać płatności na Solanie.

Najczęściej wybierane opcje to:

• LangChain — workflow agentów w Pythonie lub JavaScripcie
• CrewAI — orkiestracja zadań wielu agentów
• Microsoft AutoGen — wieloagentowe rozmowy i przepływy pracy
• Claude MCP — wywoływanie narzędzi przez Model Context Protocol
• Coinbase AgentKit — narzędzia dla agentów zaprojektowane pod płatności krypto
• AutoGPT, Dify i n8n — kreatory agentów w stylu workflow

O tym, kiedy sięgnąć po narzędzie do wyszukiwania twarzy, decyduje framework agenta. Klient x402 zajmuje się zaś sprawdzaniem ceny, podpisem i ponawianiem żądania.

x402 a API REST

FaceCheck.ID udostępnia zarówno API REST, jak i protokół x402.

Kiedy używać x402

Wybierz endpoint x402, gdy zależy ci na:

• agentach AI prowadzących odwrotne wyszukiwanie twarzy w otwartym internecie
• braku rejestracji, klucza API i kredytów z góry
• modelu pay-per-use
• autonomicznych agentach, którzy płacą za swoje narzędzia sami
• okazjonalnych lub jednorazowych wyszukiwaniach twarzy
• jak najszybszych, priorytetowych zapytaniach

Wybierz API REST, gdy zależy ci na:

• klasycznym kluczu API
• kredytach z góry
• przewidywalnych integracjach aplikacyjnych
• użyciu po stronie serwera
• większych wolumenach lub długotrwałych integracjach

Najczęściej zadawane pytania

Czy mogę przetestować endpoint x402 za darmo?

Nie. Za każde udane wyszukiwanie płaci się w USDC na Solanie. Cena pojawia się w odpowiedzi 402 Payment Required jeszcze przed płatnością, więc agent zawsze wie z góry, ile zapłaci.

Co jeśli wyszukiwanie nie znajdzie żadnego trafienia?

Nic nie płacisz. Płatność on-chain rozlicza się tylko wtedy, gdy wyszukiwanie zwróci wyniki.

Czy potrzebuję portfela Solany?

Tak. Agent musi mieć parę kluczy Solany z USDC, żeby móc podpisywać płatności. Konto w FaceCheck nie jest potrzebne.

Dlaczego USDC, a nie zwykła waluta?

USDC na Solanie rozlicza się w kilka sekund i przy bardzo niskich opłatach. Dopiero to sprawia, że płatność agenta za każde wywołanie API — bez udziału człowieka — w ogóle ma sens w praktyce.

Czy mogę używać x402 ze zwykłej aplikacji, a nie z agenta AI?

Możesz, ale dla klasycznych aplikacji i backendów zwykle lepiej sprawdza się API REST. x402 jest zoptymalizowane pod autonomiczne użycie z płatnością za każde wywołanie.

Czy x402 działa z Claude'em, ChatGPT albo innymi agentami LLM?

Każdy framework agenta, który potrafi wysłać żądanie HTTP i podpisać transakcję na Solanie, może korzystać z tego endpointu — w tym konfiguracje tool-callingu przez Claude MCP, LangChain, CrewAI, AutoGen i inne. Zajrzyj do sekcji „Kompatybilne frameworki agentów” powyżej.

Warto przeczytać

• Dokumentacja API REST FaceCheck
• Specyfikacja Swagger
• Wskazówki dotyczące odwrotnego wyszukiwania twarzy po obrazie
• Przegląd protokołu x402
• USDC na Solanie

Wszystkie wyszukiwania w FaceCheck podlegają warunkom korzystania.