面向 AI 智能体的人脸搜索 API(x402)

FaceCheck 现已支持 AI 智能体通过 x402 协议在互联网上以脸搜人。

智能体只需提交一张人脸图片,以 Solana 上的 USDC 完成支付,即可获取匹配到的网页、缩略图和置信度评分——全程无需账号、无需注册、无需 API 密钥,也无需预充值。

什么是 x402?

x402 是一种面向 API 的支付协议。

它让 AI 智能体能够查询某次 API 请求的价格、完成支付,并通过一次普通的 HTTP 请求拿到结果——背后用的正是早就预留的 HTTP 402 Payment Required 状态码。

放到 FaceCheck 上,这意味着智能体可以在开放互联网上做反向人脸搜索,而无需 FaceCheck 账号、API 密钥或预付费用。

智能体能用它做什么?

借助 FaceCheck 的 x402 接口,AI 智能体可以:

• 在互联网上搜索匹配的人脸
• 找到某张人脸出现过的网页
• 获取匹配结果的 URL
• 拿到 base64 编码的缩略图
• 获取置信度评分

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 库的官方文档为准,核对最新的方法名和用法。

兼容的智能体框架

只要能发起 HTTP 请求并对 Solana 交易签名,任何 AI 智能体或工作流系统都可以接入 x402 接口。

常见的选择包括:

• LangChain——Python 或 JavaScript 中的智能体工作流
• CrewAI——多智能体任务编排
• Microsoft AutoGen——多智能体对话与工作流
• Claude MCP——通过 Model Context Protocol 调用工具
• Coinbase AgentKit——专为加密支付打造的智能体工具
• AutoGPT、Dify 和 n8n——工作流式的智能体搭建平台

是否调用人脸搜索这一工具,由智能体框架自行决定;价格查询、签名以及请求重试,则交给 x402 客户端去处理。

x402 与 REST API 对比

FaceCheck.ID 同时提供 REST API 和 x402 协议。

什么时候用 x402

如果符合下列任意一点,就选择 x402 接口:

• 让 AI 智能体在开放互联网上做反向人脸搜索
• 跳过注册、API 密钥与预付积分
• 按用量付费
• 让自主智能体直接为工具付费
• 偶尔或一次性地进行人脸查找
• 享受最高优先级的搜索

如果是下面这些情况,则更适合使用 REST API:

• 想要传统的 API 密钥
• 使用预付积分
• 可预期的应用集成
• 后端服务器调用
• 大批量或长期运行的集成

常见问题

x402 接口可以免费试用吗?

不可以。每次成功的搜索都需要用 Solana 上的 USDC 支付。价格会先在 402 Payment Required 响应里给出,智能体在付款前就能确切知道费用。

如果没有匹配到结果会怎样?

不收费。链上支付只在搜索返回结果时才会真正结算。

我需要 Solana 钱包吗?

需要。智能体需要一个带 USDC 的 Solana 密钥对来给支付签名,但不需要 FaceCheck 账号。

为什么用 USDC 而不是法币?

Solana 上的 USDC 几秒内就能到账,手续费也非常低,这让无人值守、按 API 调用付费的智能体场景在实际应用中真正变得可行。

我能从普通应用里用 x402,而不是 AI 智能体里吗?

可以,但对传统的应用和后端来说,REST API 通常更合适。x402 是为自主、按次付费的场景量身打造的。

x402 能配合 Claude、ChatGPT 或其他 LLM 智能体使用吗?

只要框架能发起 HTTP 请求并对 Solana 交易签名,就能接入这个接口——包括通过 Claude MCP、LangChain、CrewAI、AutoGen 等进行工具调用的方案。详见上文的「兼容的智能体框架」一节。

延伸阅读

• FaceCheck REST API 文档
• Swagger 规范
• 反向人脸搜图技巧
• x402 协议概览
• Solana 上的 USDC

所有 FaceCheck 搜索均须遵守使用条款。