API pro vyhledávání podle obličeje určené AI agentům (x402)

FaceCheck teď umožňuje AI agentům prohledávat internet podle obličeje přes protokol x402.

Agent pošle fotku obličeje, vyhledávání zaplatí v USDC na Solaně a zpátky dostane odpovídající stránky, náhledy a skóre shody — bez účtu, bez registrace, bez API klíče i bez předplacených kreditů.

Co je x402?

x402 je platební protokol pro API.

Umožňuje AI agentovi zjistit cenu API požadavku, zaplatit ji a převzít výsledek v rámci jednoho běžného HTTP požadavku — staví přitom na stavovém kódu HTTP 402 Payment Required, který byl dlouho rezervovaný právě k tomuto účelu.

V případě FaceCheck to znamená, že agent může spustit zpětné vyhledávání obličeje na otevřeném webu i bez účtu na FaceCheck, bez API klíče a bez dopředu nakoupených kreditů.

Co s tím můžou agenti dělat?

Pomocí x402 endpointu od FaceCheck můžou AI agenti:

• vyhledávat na internetu odpovídající obličeje
• najít stránky, na kterých se daný obličej objevuje
• získat URL adresy nalezených výsledků
• dostat náhledy zakódované v base64
• získat skóre shody

Endpoint x402

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

Jak to funguje

Cena

Jedno vyhledávání přes x402 endpoint stojí o něco víc než přes klasické REST API, protože v ceně už je zahrnuté zpracování on-chain platby a navíc úplně odpadá zakládání účtu.

Aktuální cena se vždy objeví v odpovědi 402 Payment Required, ještě než agent vůbec zaplatí.

Právě tahle odpověď 402 je oficiálním zdrojem ceny.

Příklad HTTP průběhu

Surový HTTP průběh má tři kroky: zjistit cenu, podepsat platbu a odeslat snímek.

1. Zjištění ceny

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

# Odpověď:
# HTTP 402 Payment Required
# Obsahuje cenu, cílovou adresu platby a detaily požadavku

2. Podepsání platby

Agent podepíše platbu svým párem klíčů pro Solanu. V produkčním prostředí tenhle krok obvykle obstará klientská knihovna x402.

3. Odeslání snímku

curl -X POST https://facecheck.id/x402/reverse-face-search \
  -H "X-PAYMENT: <podepsaná platba zakódovaná v base64>" \
  -F "images=@daniel.jpg"

# Odpověď:
# Výsledky vyhledávání v JSONu
# Platba se zúčtuje, jen když vyhledávání něco najde

Formát odpovědi

Úspěšné vyhledávání vrátí JSON se seznamem shod:

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

U každé shody dostanete zdrojovou URL, skóre shody a náhled nalezeného obličeje zakódovaný v base64.

S klientskou knihovnou

V praxi se nejvíc vyplatí použít klientskou knihovnu x402, která se postará o celý průběh automaticky:

1. zjistí cenu
2. podepíše platbu
3. pošle požadavek znovu, tentokrát už s přiloženou platbou
4. převezme výsledky vyhledávání

Příklad s knihovnou 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);

Klientské knihovny se můžou lišit. Aktuální názvy metod a způsob použití najdete v dokumentaci té x402 knihovny, kterou si vyberete.

Kompatibilní frameworky pro agenty

x402 endpoint funguje s libovolným AI agentem nebo workflow systémem, který umí poslat HTTP požadavek a podepsat platbu na Solaně.

Mezi nejčastější volby patří:

• LangChain — workflow agentů v Pythonu nebo JavaScriptu
• CrewAI — orchestrace úloh napříč více agenty
• Microsoft AutoGen — víceagentní konverzace a workflow
• Claude MCP — volání nástrojů přes Model Context Protocol
• Coinbase AgentKit — nástroje pro agenty stavěné na míru kryptoplatbám
• AutoGPT, Dify a n8n — buildery agentů ve stylu workflow

Kdy nástroj na vyhledávání obličejů použít, rozhoduje samotný framework agenta. Zjištění ceny, podpis a opakované odeslání požadavku má pak na starosti x402 klient.

x402 vs. REST API

FaceCheck.ID podporuje jak REST API, tak protokol x402.

Kdy zvolit x402

Endpoint x402 vyberte, když potřebujete:

• nechat AI agenty dělat zpětné vyhledávání obličeje na otevřeném webu
• obejít se bez registrace, API klíčů i předplacených kreditů
• platit podle skutečného využití
• autonomní agenty, kteří si své nástroje hradí sami
• občasná nebo jednorázová vyhledávání obličejů
• maximální prioritu ve frontě vyhledávání

REST API zvolte, když potřebujete:

• klasický API klíč
• předplacené kredity
• předvídatelné integrace do aplikací
• nasazení v backendových serverech
• větší objemy nebo dlouhodobé integrace

Časté dotazy

Můžu si x402 endpoint vyzkoušet zdarma?

Ne. Každé úspěšné vyhledávání se platí v USDC na Solaně. Cena se ale vrací v odpovědi 402 Payment Required ještě před platbou, takže agent vždycky předem ví, kolik ho to bude stát.

Co když se nenajde žádná shoda?

Nic neplatíte. On-chain platba proběhne, jen pokud vyhledávání vrátí výsledky.

Potřebuju Solana peněženku?

Ano. Agent potřebuje pár klíčů pro Solanu s nějakými USDC, aby měl čím platby podepisovat. Účet na FaceCheck ale potřeba není.

Proč USDC, a ne klasické peníze?

USDC na Solaně se vypořádá v řádu sekund a s velmi nízkými poplatky — teprve díky tomu má vůbec smysl, aby agent platil za každé volání API bez zásahu člověka.

Můžu x402 použít z běžné aplikace místo z AI agenta?

Můžete, ale pro klasické aplikace a backendy se obvykle hodí spíš REST API. x402 je optimalizované pro autonomní použití s platbou za každé volání.

Funguje x402 s Claudem, ChatGPT nebo dalšími LLM agenty?

Endpoint může používat jakýkoli framework agenta, který umí poslat HTTP požadavek a podepsat transakci na Solaně — včetně tool-callingu přes Claude MCP, LangChain, CrewAI, AutoGen a další. Podrobnosti najdete výše v sekci „Kompatibilní frameworky pro agenty“.

K dalšímu čtení

• Dokumentace REST API FaceCheck
• Specifikace Swagger
• Tipy pro zpětné vyhledávání obličeje podle obrázku
• Přehled protokolu x402
• USDC na Solaně

Veškerá vyhledávání na FaceCheck podléhají podmínkám použití.