x402 Image API

Generación de imágenes por IA de pago en el protocolo x402: 0,001 $/imagen, USDC en Base, sin claves de API.

Punto de conexión activo: https://x402.chaly.org · salud · OpenAPI 3.1 · .well-known/x402 · llms.txt

El estándar x402 recupera el código HTTP 402 Payment Required para pagos nativos de máquina: un comprador (humano o agente de IA) envía un prompt mediante POST, recibe una oferta de pago firmada en la cabecera PAYMENT-REQUIRED, autoriza una transferencia USDC EIP-3009 con su monedero, reintenta la solicitud y un facilitador externo verifica y liquida en cadena. Sin cuentas, sin claves de API, sin gas para el comprador: el pago ES la autenticación.

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

Precios

• Total cobrado = por imagen × cantidad (count 1–8, o lote items: [["prompt", n], …], total ≤ 8).

• La relación de aspecto es gratuita.

• Existen niveles superiores en la tabla de precios interna, pero solo se anuncian los niveles disponibles.

• Los precios son dinámicos: la oferta 402 se calcula por solicitud a partir del cuerpo (PRICE_TABLE en server.js), de modo que lo que se pide al comprador es exactamente lo que genera el manejador.

Related MCP server: Nexus MCP

Inicio rápido del comprador

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"

Consulta client.mjs para ver un cliente ejecutable completo (incluida la consulta periódica).

Servidor MCP

mcp-server.mjs expone la API como herramientas MCP (image_generate, image_health, image_openapi, image_poll) para que los agentes de programación puedan generar imágenes directamente:

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

Las herramientas gratuitas (health/openapi/poll) funcionan sin clave.

Autoalojamiento

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

Variables de entorno clave: PAY_TO_ADDRESS, X402_NETWORK (eip155:8453), X402_FACILITATOR_URL (p. ej., PayAI), PORT, OUT_DIR, PUBLIC_URL, MAX_COUNT, además de MEDIA_IO_PROJECT_DIR — ruta a tu backend de generación.

Backend conectable: la capa Express ejecuta un subproceso de trabajo puntual por solicitud y lee una única línea JSON de la salida estándar. Este repositorio incluye el lado del vendedor; nuestro propio worker de puente (gen_worker.py) se mantiene privado. Para conectar tu propio generador, proporciona un ejecutable que

• lea {prompt, aspect, megapixels, quality, count, …} como JSON en la entrada estándar,

• escriba {ok, urls: [...], …} como última línea de la salida estándar,

• termine con un código distinto de cero en caso de error.

Exposición pública (sin VPS)

Un Cloudflare Tunnel es la única puerta de entrada: TLS termina en el borde de Cloudflare y un origen caído devuelve 503/530 automáticamente (latido gratuito). Guía completa en cloudflared/README.md; scripts de lanzamiento paralelos en scripts/ (+ unidades systemd para Linux).

Notas de diseño

• El orden del middleware importa: express.json() se ejecuta antes que el middleware de pago para que la función de precio dinámico pueda leer el cuerpo analizado; de lo contrario, un lote de 0,008 $ se cotiza silenciosamente como una imagen de 0,001 $.

• Control de capacidad antes del pago: un middleware previo al pago devuelve 503 insufficient_capacity cuando no hay ninguna ranura de generación disponible actualmente, lo que cortocircuita antes de cualquier 402: los compradores nunca firman algo que no podemos entregar.

• 202 + sondeo en lugar de respuestas de larga duración: la generación tarda entre 50 y 90 s/imagen; devolver un identificador de trabajo de inmediato evita los tiempos de espera de la puerta de enlace (límite de 100 s de Cloudflare) para lotes de hasta 8 imágenes.

• Salida de marca blanca: los PNG se guardan en GET /images/:file (nombres hash, protegidos contra recorridos de ruta) servidos desde tu dominio.

• Descubrimiento en Bazaar: declareDiscoveryExtension expone este servicio en el Bazaar de x402; los agentes pueden encontrarlo sin que se les indique la URL.

• Idempotencia: pasa "id" para deduplicar reintentos: los resultados en caché se devuelven sin regenerar (orders.jsonl + trabajos en memoria).

Seguridad

• El servidor solo conserva tu dirección pública de recepción; la liquidación se facilita en cadena y llega a tu monedero.

• .env, jobs.json, orders.jsonl están en gitignore: nunca los confirmes.

• Usa un monedero dedicado para PAY_TO_ADDRESS; mantén las tesorerías en frío.

Licencia

MIT