AIエージェント向け 顔検索API(x402)

FaceCheckはx402プロトコルに対応し、AIエージェントが顔写真でインターネットを検索できるようになりました。

エージェントは顔の画像を送信し、Solana上のUSDCで検索料金を支払うだけで、ヒットしたページ・サムネイル・一致度スコアを受け取れます。アカウント登録もAPIキーもプリペイドのクレジットも要りません。

x402とは

x402は、APIのための支払いプロトコルです。

AIエージェントがAPIリクエストの料金を確認し、その場で支払い、結果を1回のHTTPリクエストで受け取れるようにします。長年未使用のまま予約されてきたHTTPステータスコード HTTP 402 Payment Required を活用したものです。

FaceCheckの場合で言えば、エージェントはFaceCheckのアカウントもAPIキーもプリペイドクレジットも持たないまま、オープンなウェブ上で逆顔検索を実行できる、ということになります。

エージェントは何ができる?

FaceCheckのx402エンドポイントを使うと、AIエージェントは次のことができます。

• インターネット上で一致する顔を検索する
• その顔が写っているウェブページを見つける
• ヒットしたページのURLを取得する
• base64形式のサムネイルを受け取る
• 一致度スコアを取得する

x402 エンドポイント

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

仕組み

料金

x402エンドポイントは通常のREST APIより1回あたりのコストが少し高めです。オンチェーン決済の処理を含み、アカウントの設定もまったく不要だからです。

現在の料金は、エージェントが実際に支払う前の 402 Payment Required レスポンスに必ず示されます。

この 402 レスポンスこそが、料金の正式な情報源です。

HTTPフローの例

生のHTTPフローは「料金を確認する」「支払いに署名する」「画像を送信する」の3ステップです。

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 と 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のすべての検索は利用規約の対象となります。