API поиска по лицу для AI-агентов (x402)

FaceCheck позволяет AI-агентам искать людей в интернете по лицу по протоколу x402.

Агент отправляет изображение с лицом, оплачивает поиск в USDC на Solana и получает в ответ подходящие веб-страницы, миниатюры и оценки совпадения — без аккаунта, регистрации, API-ключа и предварительной оплаты кредитов.

Что такое x402?

x402 — это платёжный протокол для API.

Он позволяет AI-агенту узнать стоимость запроса, оплатить его и получить результат в рамках одного обычного HTTP-запроса — на базе давно зарезервированного кода состояния HTTP 402 Payment Required.

Применительно к FaceCheck это значит, что агент может выполнить обратный поиск по лицу в открытом интернете без аккаунта в FaceCheck, без API-ключа и без заранее купленных кредитов.

Что агенты могут с этим делать?

Через эндпоинт x402 от FaceCheck AI-агенты могут:

• искать в интернете совпадающие лица
• находить страницы, где встречается лицо
• получать URL найденных совпадений
• получать миниатюры в base64
• получать оценки уверенности (confidence)

Эндпоинт x402

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

Как это работает

Цена

Один поиск через эндпоинт x402 стоит немного дороже, чем через стандартный REST API: в цену уже заложена обработка ончейн-платежа, и при этом никакая настройка аккаунта не нужна.

Текущая цена всегда указана в ответе 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..."
    }
  ]
}

В каждом совпадении — URL источника, оценка совпадения и миниатюра найденного лица в 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 работает с любым AI-агентом или workflow-системой, которая умеет отправлять HTTP-запросы и подписывать платежи Solana.

Самые распространённые варианты:

• LangChain — workflow-агенты на Python или JavaScript
• CrewAI — оркестрация задач между несколькими агентами
• Microsoft AutoGen — многоагентные диалоги и workflow
• Claude MCP — вызов инструментов через Model Context Protocol
• Coinbase AgentKit — инструменты для агентов, заточенные под крипто-платежи
• AutoGPT, Dify и n8n — конструкторы агентов в стиле workflow

Когда задействовать инструмент поиска по лицу, решает сам фреймворк агента. А клиент x402 берёт на себя получение цены, подпись и повторную отправку запроса.

x402 и REST API

FaceCheck.ID поддерживает и REST API, и протокол x402.

Когда выбирать x402

Эндпоинт x402 подойдёт, если вам нужно:

• чтобы AI-агенты сами вели обратный поиск по лицу в открытом интернете
• обойтись без регистрации, API-ключей и предоплаченных кредитов
• платить только за фактическое использование
• иметь автономных агентов, которые сами платят за свои инструменты
• проводить редкие или разовые поиски по лицу
• получать максимальный приоритет в очереди поиска

REST API подойдёт, если вам нужно:

• использовать классический API-ключ
• работать с предоплаченными кредитами
• строить предсказуемые интеграции с приложениями
• обращаться к API с серверного бэкенда
• обрабатывать большие объёмы или поддерживать долгие интеграции

Частые вопросы

Можно ли попробовать эндпоинт x402 бесплатно?

Нет. Каждый успешный поиск оплачивается в USDC на Solana. Цена приходит в ответе 402 Payment Required ещё до оплаты — так что агент всегда знает стоимость заранее.

А если совпадений не найдено?

Тогда списания нет. Ончейн-платёж проводится только в том случае, если поиск возвращает результаты.

Нужен ли кошелёк Solana?

Да. Агенту нужна пара ключей Solana с USDC, чтобы подписывать платежи. Аккаунт FaceCheck при этом не требуется.

Почему USDC, а не обычные деньги?

Переводы USDC на Solana проходят за секунды и с очень низкой комиссией — именно поэтому агентам в принципе имеет смысл платить за каждый вызов API без участия человека.

Можно ли использовать x402 из обычного приложения, а не из AI-агента?

Можно, но для классических приложений и бэкендов обычно лучше подходит REST API. x402 заточен под автономное использование и оплату за каждый вызов.

Работает ли x402 с Claude, ChatGPT или другими LLM-агентами?

С эндпоинтом может работать любой фреймворк агента, который умеет отправлять HTTP-запросы и подписывать транзакции Solana, — в том числе варианты с tool-calling через Claude MCP, LangChain, CrewAI, AutoGen и другие. Подробнее — в разделе «Совместимые фреймворки агентов» выше.

Что почитать ещё

• Документация REST API FaceCheck
• Спецификация Swagger
• Советы по обратному поиску лица по изображению
• Обзор протокола x402
• USDC на Solana

Все поиски FaceCheck выполняются на условиях Пользовательского соглашения.