x402 Image API

유료 AI 이미지 생성, x402 프로토콜 기반 — 이미지당 $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 전송을 승인하고, 요청을 재시도합니다. 그리고 제3자 파실리테이터가 온체인에서 검증하고 정산합니다. 계정도, API 키도, 구매자의 가스도 필요 없습니다 — 결제가 곧 인증(auth)입니다.

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 (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: [...], …}를 기록하고,

• 실패 시 0이 아닌 종료 코드로 종료합니다.

공개 노출 (VPS 없이)

Cloudflare Tunnel이 유일한 수신 경로입니다. TLS는 Cloudflare 엣지에서 종료되며, 원본 서버가 다운되면 자동으로 503/530을 제공합니다(무료 heartbeat). 전체 워크스루는 cloudflared/README.md에 있고, 병렬 런처 스크립트는 scripts/(Linux용 systemd 유닛 포함)에서 확인할 수 있습니다.

설계 노트

• 미들웨어 순서가 중요: express.json()이 결제 미들웨어보다 먼저 실행되어 동적 가격 함수가 파싱된 본문을 읽을 수 있습니다. 그렇지 않으면 $0.008 배치가 하나의 $0.001 이미지로 잘못 계산됩니다.

• 결제 전 용량 게이트: 오늘 생성 슬롯을 확보할 수 없는 경우 결제 전 미들웨어가 503 insufficient_capacity를 반환하여 402 요청 이전의 요청을 차단합니다. 구매자가 제공할 수 없는 결과에 서명하는 일을 방지합니다.

• 202 + 폴링(장기 응답 대신): 생성은 이미지당 약 50–90초가 걸리므로 작업 핸들을 즉시 반환하면 최대 8개 이미지 배치에 대해 게이트웨이 시간 초과(Cloudflare 100초 제한)를 피할 수 있습니다.

• 화이트 라벨 출력: PNG는 GET /images/:file에 저장되며(해시 이름, 경로 탐색 방지) 사용자 도메인에서 제공됩니다.

• Bazaar 디스커버리: declareDiscoveryExtension을 통해 이 서비스를 x402 Bazaar에 노출하므로 에이전트는 URL을 미리 알지 못해도 서비스를 찾을 수 있습니다.

• 멱등성: "id"를 전달하여 중복 시도를 제거하면 캐시된 결과가 재생성 없이 돌아옵니다(orders.jsonl + 메모리 내 작업).

보안

• 서버는 사용자의 공개 수신 주소만 보유합니다. 결제는 온체인에서 파실리테이션되어 지갑에 입금됩니다.

• .env, jobs.json, orders.jsonl은 gitignore 처리됩니다 — 커밋하지 마세요.

• PAY_TO_ADDRESS에는 전용 지갑을 사용하고, 금고는 콜드월렛으로 유지하세요.

라이선스

MIT