x402 Image API

Bezahlte KI-Bildgenerierung über das x402-Protokoll – $0.001/Bild, USDC auf Base, keine API-Schlüssel.

Live-Endpunkt: https://x402.chaly.org · health · OpenAPI 3.1 · .well-known/x402 · llms.txt

Der x402-Standard belebt HTTP 402 Payment für Zahlungen zwischen Maschinen neu: Ein Käufer (Mensch oder KI-Agent) sendet per POST einen Prompt, erhält ein signiertes Zahlungsangebot im PAYMENT-REQUIRED-Header, autorisiert mit seiner Wallet eine EIP-3009-USDC-Übertragung, wiederholt die Anfrage, und ein Drittanbieter-Facilitator verifiziert und wickelt das Settlement onchain ab. Keine Konten, keine API-Schlüssel, keine Gasgebühren für den Käufer – die Zahlung IST die Authentifizierung.

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

Preise

• Der Gesamtpreis = Einzelpreis × Anzahl (count 1–8, oder Batch items: [["prompt", n], …], gesamt ≤ 8).

• Das Seitenverhältnis ist kostenlos.

• Größere Stufen existieren in der internen Preistabelle, ausgewiesen werden aber nur auslieferbare Stufen.

• Das Pricing ist dynamisch: Das 402-Angebot wird pro Anfrage aus dem body berechnet (PRICE_TABLE in server.js), sodass der Käufer genau die Zahlung angeboten bekommt, die vom Handler generiert wird.

Related MCP server: Nexus MCP

Schnellstart für Käufer

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"

Eine vollständig lauffähigen Client (inklusive Polling) findest du in client.mjs.

MCP-Server

mcp-server.mjs stellt die API als MCP-Tools bereit (image_generate, image_health, image_openapi, image_poll), sodass Coding-Agenten direkt Bilder generieren können:

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

Die nicht zahlungspflichtigen Tools (health/openapi/poll) funktionieren ohne Schlüssel.

Selbsthosting

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

Wichtige Umgebungsvariablen: PAY_TO_ADDRESS, X402_NETWORK (eip155:8453), X402_FACILITATOR_URL (z. B. PayAI), PORT, OUT_DIR, PUBLIC_URL, MAX_COUNT sowie MEDIA_IO_PROJECT_DIR – der Pfad zu deinem Generation-Backend.

Plug-bar-Backend: Die Express-Layer startet pro Anfrage einen einmaligen Worker-Subprozess und liest eine einzelne JSON-Zeile als letzte stdout-Ausgabe. Dieses Repository liefert den eigentlichen Bridge-Worker (gen_worker.py) nicht mit; er wird privat gehalten. Um einen eigenen Generator anzubinden, stelle ein ausführbares Programm bereit, das

• {prompt, aspect, megapixels, quality, count, …} als JSON von stdin liest,

• {ok, urls: [...], …} als letzte stdout-Zeile schreibt,

• im Fehlerfall mit einem Exit-Code ungleich 0 endet.

Öffentliche Bereitstellung (ohne VPS)

Ein Claude? No.

A Cloudflare Tunnel ist der einzige Eingang – TLS endet an Cloudflares Edge und ein ausgefallener Origin-Server liefert automatisch 503/530 aus (kostenloser Heartbeat). Die vollständige Anleitung steht in cloudflared/README.md; parallele Startskripte gibt es in scripts/ (+ systemd-Units für Linux).

Design-Hinweise

• Middleware-Reihenfolge ist wichtig: express.json() läuft vor der Payment-Middleware, damit die Dynamik-Preis-Funktion den geparsten Body lesen kann – sonst wird ein $0.008-Batch stillschweigend als ein einzelnes $0.001-Bild angeboten.

• Kapazitäts-Gate vor der Zahlung: Eine Middleware vor der Zahlung gibt 503 insufficient_capacity zurück, wenn heute kein Generierungsslot verfügbar ist, und bricht damit ab bevor ein 402 ausgelöst wird – Käufer signieren nichts, das wir nicht liefern können.

• 202 + Polling statt langlaufender Antworten: Die Erzeugung dauert ~50–90 s/Bild. Ein Job-Handle wird sofort zurückgegeben, vermeidet so Gateway-Timeouts (Cloudflare-Grenze von 100 s) und eignet sich für Batches mit bis zu 8 Bildern.

• White-Label-Ausgabe: PNGs landen unter GET /images/:file (Hash-Namen, Trafficking guards) und werden von deiner Domain served.

• Bazaar-Entdeckung: declareDiscoveryExtension macht den Dienst über den x402 Bazaar auffindbar; Agenten können ihn finden, ohne die URL zu kennen.

• Idempotenz: "id" rendert deduziert – gecachte Ergebnisse werden ohne Neu-Generierung zurückgegeben (orders.jsonl + In-Memory-Jobs).

Sicherheit

• Der Server hält ausschließlich deine öffentliche Empfangsadresse; das Settlement erfolgt onchain und landet in deiner Wallet.

• .env, jobs.json und orders.jsonl sind gitignored – committe sie niemals.

• Verwende eine eigene Wallet für PAY_TO_ADDRESS; Tresore kühlst aufbewahren.

Lizenz

MIT