x402 Image API

基于 x402 协议 的付费 AI 图像生成 — $0.001/张，Base 上的 USDC，无需 API 密钥。

在线端点：https://x402.chaly.org · health · OpenAPI 3.1 · .well-known/x402 · llms.txt

x402 标准为机器原生支付复兴了 HTTP 402 Payment Required：买家（人类或 AI 代理）POST 一个提示词，在 PAYMENT-REQUIRED 头中收到签名的支付报价，用其钱包授权一笔 EIP-3009 USDC 转账，重试请求，然后由第三方促进者验证并在链上结算。无需账户、无需 API 密钥、买家无需 gas——支付即认证。

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: [...]}

定价

• 总收费 = 每张图像 × 数量（count 1–8，或批量 items: [["prompt", n], …]，总计 ≤ 8）。

• 宽高比免费。

• 内部价格表中存在更大的档位，但只公布可服务的档位。

• 定价是动态的：402 报价根据请求体按请求计算 （server.js 中的 PRICE_TABLE），因此买家被要求支付的金额与处理器生成的完全一致。

Related MCP server: forgemesh-imagegen

买家快速入门

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 层为每个请求派生一个一次性 worker 子进程，并从 stdout 读取单行 JSON。本仓库提供卖方端；我们自己的桥接 worker（gen_worker.py）保持私有。要接入你自己的生成器，请提供一个可执行文件，它需要

• 从 stdin 读取 {prompt, aspect, megapixels, quality, count, …} 作为 JSON，

• 将 {ok, urls: [...], …} 作为最后一行 stdout 输出，

• 失败时以非零状态退出。

公网访问（无需 VPS）

Cloudflare Tunnel 是唯一的入口——TLS 在 Cloudflare 边缘终止，源站宕机时自动返回 503/530（免费心跳）。完整教程见 cloudflared/README.md；配套的启动脚本位于 scripts/（+ 适用于 Linux 的 systemd 单元）。

设计说明

• 中间件顺序很重要：express.json() 在支付中间件之前运行，以便动态定价函数能读取解析后的请求体——否则一个 $0.008 的批次会被静默地按一张 $0.001 的图像报价。

• 支付前容量门控：当今天没有可认领的生成槽位时，支付前中间件返回 503 insufficient_capacity，在任何 402 之前短路——买家绝不会为我们无法交付的内容签名。

• 202 + 轮询而非长连接响应：生成每张图像需要约 50–90 秒；立即返回作业句柄可避免网关超时（Cloudflare 的 100 秒限制），适用于最多 8 张图像的批次。

• 白标输出：PNG 文件位于 GET /images/:file（哈希文件名，防目录遍历），从你的域名提供。

• Bazaar 发现：declareDiscoveryExtension 在 x402 Bazaar 中暴露此服务；代理无需被告知 URL 即可找到它。

• 幂等性：传入 "id" 以对重试去重——无需重新生成即可返回缓存结果（orders.jsonl + 内存中的作业）。

安全

• 服务器只保存你的公开收款地址；结算在链上完成并进入你的钱包。

• .env、jobs.json、orders.jsonl 已被 gitignore——切勿提交它们。

• 为 PAY_TO_ADDRESS 使用专用钱包；保持资金库冷存储。

许可证

MIT