x402 画像API

x402プロトコル上の有料AI画像生成 — $0.001/枚、Base上のUSDC、APIキー不要。

ライブエンドポイント: https://x402.chaly.org · ヘルス · OpenAPI 3.1 · .well-known/x402 · llms.txt

x402標準は、マシンネイティブな支払いのためにHTTP 402 Payment Requiredを復活させます。買い手（人間またはAIエージェント）はプロンプトをPOSTし、PAYMENT-REQUIREDヘッダーで署名済みの支払いオファーを受け取り、ウォレットでEIP-3009 USDC転送を承認し、リクエストを再試行します。第三者のファシリテーターがオンチェーンで検証・決済します。アカウント不要、APIキー不要、買い手のガス不要 — 支払いが認証です。

POST /generate {prompt}          → 402 + PAYMENT-REQUIRED (machine-readable offer)
   ↳ buyer signs EIP-3009 authorization (USDC on Base)
POST /generate {prompt} + PAYMENT-SIGNATURE
                                 → 202 {jobId, pollUrl, estimatedSeconds}
GET  /result/:id every ~5s       → processing … → done {urls: [...]}

料金

• 合計請求額 = 1枚あたり × 枚数（count 1〜8、またはバッチ items: [["prompt", n], …]、合計 ≤ 8）。

• アスペクト比は無料。

• 内部の価格表にはより大きなティアが存在しますが、提供可能なティアのみが宣伝されます。

• 価格は動的です：402オファーはリクエストごとにボディから計算されます（server.jsのPRICE_TABLE）。そのため、買い手に請求される金額は、ハンドラーが生成するものと正確に一致します。

Related MCP server: Nexus MCP

買い手クイックスタート

npm i @x402/fetch @x402/evm viem

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.BUYER_PRIVATE_KEY);
const fetchWithPay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});

// 402 → auto-pay → retry → 202 {jobId, pollUrl}
const res = await fetchWithPay("https://x402.chaly.org/generate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ prompt: "a red cube on a blue table", count: 1 }),
});
const job = await res.json();
// poll GET job.pollUrl every 5s until status === "done"

完全な実行可能なクライアント（ポーリングを含む）については、client.mjsを参照してください。

MCPサーバー

mcp-server.mjsは、APIをMCPツール（image_generate、image_health、image_openapi、image_poll）として公開し、コーディングエージェントが直接画像を生成できるようにします：

{
  "mcpServers": {
    "x402-image-api": {
      "command": "node",
      "args": ["mcp-server.mjs"],
      "env": {
        "X402_API_URL": "https://x402.chaly.org",
        "BUYER_PRIVATE_KEY": "0x…"
      }
    }
  }
}

無料ツール（health/openapi/poll）はキーなしで動作します。

セルフホスティング

npm install
cp .env.example .env      # set PAY_TO_ADDRESS (public address only!)
npm start                 # node --env-file=.env server.js → :4021

主要な環境変数：PAY_TO_ADDRESS、X402_NETWORK（eip155:8453）、X402_FACILITATOR_URL（例：PayAI）、PORT、OUT_DIR、PUBLIC_URL、MAX_COUNT、さらにMEDIA_IO_PROJECT_DIR — 生成バックエンドへのパス。

プラグ可能なバックエンド： Expressレイヤーはリクエストごとにワンショットのワーカーサブプロセスを起動し、stdoutから単一のJSON行を読み取ります。このリポジトリは売り手側を提供します。私たち自身のブリッジワーカー（gen_worker.py）は非公開です。独自のジェネレーターをプラグインするには、以下の実行可能ファイルを提供してください：

• stdinでJSONとして{prompt, aspect, megapixels, quality, count, …}を読み取り、

• 最後のstdout行として{ok, urls: [...], …}を書き出し、

• 失敗時は非ゼロで終了します。

パブリック公開（VPS不要）

Cloudflare Tunnelが唯一の入口です — TLSはCloudflareのエッジで終端され、ダウンしたオリジンは自動的に503/530を返します（無料のハートビート）。完全なウォークスルーはcloudflared/README.mdにあります。並列ランチャースクリプトはscripts/にあります（Linux用のsystemdユニットも含む）。

設計ノート

• ミドルウェアの順序が重要：express.json()は支払いミドルウェアの前に実行され、動的価格関数が解析済みボディを読み取れるようにします。そうしないと、$0.008のバッチが$0.001の画像1枚として静かに見積もられます。

• 支払い前の容量ゲート：前払いミドルウェアは、今日生成スロットを取得できない場合に503 insufficient_capacityを返し、402の前に短絡します — 買い手は私たちが提供できないものに署名することはありません。

• 長時間応答の代わりに202 + ポーリング：生成には1枚あたり約50〜90秒かかります。ジョブハンドルを即座に返すことで、最大8枚のバッチでゲートウェイのタイムアウト（Cloudflareの100秒制限）を回避します。

• ホワイトラベル出力：PNGはGET /images/:file（ハッシュ名、トラバーサルガード付き）の下に配置され、あなたのドメインから提供されます。

• バザールディスカバリー：declareDiscoveryExtensionはこのサービスをx402バザールに公開します。エージェントはURLを知らされなくてもそれを見つけることができます。

• 冪等性："id"を渡すと再試行を重複排除します — キャッシュされた結果が再生成なしで返されます（orders.jsonl + インメモリジョブ）。

セキュリティ

• サーバーはあなたの公開受信アドレスのみを保持します。決済はオンチェーンで促進され、あなたのウォレットに入金されます。

• .env、jobs.json、orders.jsonlはgitignoreされています — 決してコミットしないでください。

• PAY_TO_ADDRESSには専用ウォレットを使用し、トレジャリーはコールドに保ってください。

ライセンス

MIT