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 라이브러리의 공식 문서를 확인해 주세요.

호환되는 에이전트 프레임워크

x402 엔드포인트는 HTTP 요청을 보내고 Solana 결제에 서명할 수 있는 어떤 AI 에이전트나 워크플로 시스템과도 함께 사용할 수 있습니다.

자주 쓰이는 옵션은 다음과 같습니다.

• LangChain — Python 또는 JavaScript용 에이전트 워크플로
• CrewAI — 다중 에이전트 작업 오케스트레이션
• Microsoft AutoGen — 다중 에이전트 대화와 워크플로
• Claude MCP — Model Context Protocol을 통한 도구 호출
• Coinbase AgentKit — 암호화폐 결제를 전제로 만들어진 에이전트 도구
• AutoGPT, Dify, n8n — 워크플로 방식의 에이전트 빌더

얼굴 검색 도구를 언제 사용할지는 에이전트 프레임워크가 결정합니다. 가격 확인, 서명, 요청 재시도는 x402 클라이언트가 맡습니다.

x402 vs 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 호출마다 결제하는 방식이 실제로 쓸 만해집니다.

AI 에이전트가 아니라 일반 앱에서 x402를 써도 되나요?

가능합니다. 다만 일반적인 앱과 백엔드에는 보통 REST API가 더 잘 맞습니다. x402는 자율적인 호출별 결제 방식에 최적화되어 있습니다.

Claude, ChatGPT 또는 다른 LLM 에이전트에서도 x402가 작동하나요?

HTTP 요청을 보내고 Solana 트랜잭션에 서명할 수 있는 에이전트 프레임워크라면 이 엔드포인트를 쓸 수 있습니다 — Claude MCP, LangChain, CrewAI, AutoGen 등에서의 도구 호출 구성도 모두 포함됩니다. 자세한 내용은 위의 ‘호환되는 에이전트 프레임워크’ 섹션을 참고해 주세요.

더 읽을거리

• FaceCheck REST API 문서
• Swagger 스펙
• 이미지로 하는 얼굴 역검색 팁
• x402 프로토콜 개요
• Solana 위의 USDC

FaceCheck의 모든 검색은 이용 약관의 적용을 받습니다.