x402-vision-cropper

Servidor MCP que permite a agentes de IA recortar capturas de pantalla en regiones de píxeles exactas antes de la inferencia de LLM de visión, pagando 0.0005 USDC por recorte en Base L2 a través de x402, sin necesidad de clave API.

Ver en onrender.comPrueba este MCPPatrocinado

Documentación

Recortador de Sub-Elementos de Visión IA x402

llms.txt — contrato de servicio legible por máquina para agentes de IA autónomos

Especificación: https://llmstxt.org

API de recorte de imágenes sin estado para agentes de IA. Envíe una captura de pantalla en base64 y coordenadas de cuadro delimitador en píxeles, reciba un sub-elemento recortado como PNG en base64. Protegido por un micropago de 0.0005 USDC en Base L2. Diseñado para reducir los costos de tokens de LLM de visión al aislar solo la región de pantalla de interés antes de la inferencia.

Identidad del Servicio

  • Nombre: x402 AI Vision Sub-Element Cropper
  • Versión: 1.0.0
  • Protocolo: HTTP/1.1, JSON
  • Autenticación: micropago x402 (sin claves API, sin cuentas)
  • Estado: Sin estado — sin sesión, sin datos almacenados, sin base de datos

Protocolo de Pago

Esta API utiliza el patrón HTTP 402 Payment Required para pagos autónomos de máquina a máquina.

Paso 1 — Activar el desafío

Realice cualquier solicitud a POST /crop sin un encabezado de pago. Recibirá una respuesta 402 que contiene instrucciones de pago tanto en el cuerpo de la respuesta como en los encabezados HTTP.

Paso 2 — Pagar en cadena

Transfiera exactamente la cantidad requerida de USDC a la billetera del destinatario en la red especificada. Los valores requeridos son legibles por máquina en los encabezados de la respuesta 402:

  • x-payment-price-usdc: cantidad en USDC (ej. 0.0005)
  • x-payment-recipient: dirección de la billetera de destino
  • x-payment-network: nombre de la red (ej. base)
  • x-payment-chain-id: ID de cadena EVM (ej. 8453 para Base mainnet)
  • x-payment-token: siempre USDC
  • x-payment-token-contract: dirección del contrato USDC en esa red
  • x-payment-submit-header: nombre del encabezado a usar al reenviar

Paso 3 — Reenviar con prueba

Reintente la solicitud POST /crop idéntica, agregando el encabezado de hash de transacción:

x-payment-tx-hash: 0x<your_transaction_hash>

El servidor verifica la transacción en cadena (comprueba el estado del recibo, el registro de Transferencia USDC, la dirección del destinatario y el monto), luego ejecuta el recorte y devuelve el resultado.

Reglas de pago

  • Un pago por solicitud. Cada hash de transacción es de un solo uso dentro de una ventana de 60 segundos.
  • No reutilice hashes de transacción en solicitudes concurrentes — el servidor rechazará duplicados.
  • Si el servidor devuelve un error 5xx después de aceptar su pago, el hash de transacción se libera y puede reintentar con el mismo hash.
  • Si el servidor devuelve un error 4xx después de aceptar su pago (ej. coordenadas inválidas), el hash de transacción se consume. Pague nuevamente para una nueva solicitud.

Endpoints

POST /crop

Recorta una región rectangular de una imagen codificada en base64.

Encabezados de solicitud:

  • Content-Type: application/json (requerido)
  • x-payment-tx-hash: 0x<tx_hash> (requerido después del pago)

Cuerpo de la solicitud (JSON):

  • image (cadena, requerido): Imagen fuente codificada en base64. NO incluya un prefijo de URI de datos (sin "data:image/png;base64," — elimínelo primero). Admite PNG, JPEG, WebP, AVIF, TIFF, GIF.
  • x (entero, requerido): Borde izquierdo de la región de recorte en píxeles. Debe ser >= 0.
  • y (entero, requerido): Borde superior de la región de recorte en píxeles. Debe ser >= 0.
  • width (entero, requerido): Ancho de la región de recorte en píxeles. Debe ser >= 1.
  • height (entero, requerido): Alto de la región de recorte en píxeles. Debe ser >= 1.

Las coordenadas se asignan directamente a la salida de getBoundingClientRect() de las herramientas de automatización de navegador. Se aplica truncamiento de enteros si se pasan flotantes.

Respuesta exitosa (200):

{
  "success": true,
  "data": {
    "base64": "<PNG image as base64 string>",
    "mime": "image/png",
    "width": 640,
    "height": 80,
    "bytes": 14821,
    "clamped": false
  },
  "meta": {
    "tx_hash": "0x...",
    "crop_input": { "x": 120, "y": 45, "width": 640, "height": 80 }
  }
}

La salida es siempre PNG (sin pérdida). Adecuado para incrustación directa en prompts de LLM de visión como URI de datos base64: anteponga "data:image/png;base64," a la cadena base64 devuelta.

El campo "clamped" es verdadero si la región de recorte solicitada se extendió más allá de los límites de la imagen y se redujo automáticamente para ajustarse. Recalibre su fuente de coordenadas si recibe clamped: true.

Respuesta 402 (sin pago o pago inválido):

{
  "error": "Payment Required",
  "code": 402,
  "payment": {
    "amount_usdc": "0.0005",
    "recipient_wallet": "0x...",
    "network": "base",
    "chain_id": 8453,
    "token": "USDC",
    "token_contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "instructions": "Transfer 0.0005 USDC to 0x... on base (chain 8453), then retry with the transaction hash in the 'x-payment-tx-hash' header."
  }
}

Respuestas de error:

  • 400: Cuerpo de solicitud malformado o datos de imagen inválidos
  • 402: Pago requerido, inválido o reproducido
  • 413: El cuerpo de la solicitud excede el límite de tamaño (~14 MB)
  • 422: La región de recorte está completamente fuera de los límites de la imagen
  • 500: Error de procesamiento del lado del servidor (el hash de transacción se libera; seguro reintentar)

GET /health

Verificación de actividad. No requiere pago.

Respuesta (200):

{
  "status": "ok",
  "service": "x402-vision-cropper",
  "ts": "2025-01-01T00:00:00.000Z",
  "replay_guard": { "tracked_hashes": 0 }
}

Patrón de Integración para Agentes

1. GET /health                          → confirm service is live
2. POST /crop (no payment header)       → receive 402 + payment.instructions
3. Parse x-payment-recipient, x-payment-price-usdc, x-payment-chain-id
4. Execute USDC transfer on Base L2
5. Wait for transaction confirmation (1+ block)
6. POST /crop (same body + x-payment-tx-hash header) → receive cropped PNG
7. Prepend "data:image/png;base64," to data.base64
8. Pass to vision LLM as image input

Casos de Uso Recomendados

  • OCR en elementos de interfaz específicos (botones, etiquetas, campos de entrada, celdas de tabla)
  • Pruebas de regresión visual en componentes aislados
  • Extracción de campos de precio, stock o datos de paneles financieros
  • Lectura de sub-regiones CAPTCHA antes de pasarlas a solucionadores especializados
  • Cualquier tarea donde una llamada de visión de captura de pantalla completa sea ineficiente o inexacta

Restricciones y Límites

  • Entrada máxima de imagen: ~10 MB decodificados (14 MB en base64)
  • Dimensión máxima de recorte: 4000px por lado
  • Solicitudes concurrentes: optimizado para 10–13 solicitudes simultáneas
  • Sin almacenamiento persistente: todos los datos se descartan después de cada respuesta
  • Ventana de reproducción: los hashes de transacción se bloquean durante 60 segundos, máximo 1000 rastreados simultáneamente
  • Formato de salida: siempre PNG, independientemente del formato de entrada

Detalles de Red

  • Red de pago: Base (Base mainnet, ID de cadena 8453)
  • Contrato USDC en Base: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
  • Gas: casi cero (Base L2)
  • Liquidación: típicamente 1–2 segundos

Opcional: llms-full.txt completo

Consulte /llms-full.txt para ejemplos extendidos que incluyen pseudocódigo de agentes de múltiples pasos, flujos de recuperación de errores y patrones de extracción de coordenadas de marcos comunes de automatización de navegador (Playwright, Puppeteer, Selenium).