Guía de Integración para Desarrolladores — API de Clear Canvas

Inicio Rápido

Envía una solicitud POST con tu imagen como cuerpo en bruto. No se necesita encabezado de autorización — la API usa x402 para el pago.

# Step 1: discovery — returns HTTP 402 with payment details
curl -X POST https://x402.clearcanvas.app/v1/remove-background \
  -H "Content-Type: image/png" \
  --data-binary @photo.png

# Step 2: paid request — attach X-PAYMENT header with signed USDC transfer
curl -X POST https://x402.clearcanvas.app/v1/remove-background \
  -H "Content-Type: image/png" \
  -H "X-PAYMENT: <base64-signed-payload>" \
  --data-binary @photo.png \
  --output result.png

Autenticación mediante x402

x402 es un protocolo de pago HTTP estándar. En la primera solicitud, la API devuelve HTTP 402 con los detalles de pago. Firma una transferencia USDC en Base usando el Coinbase x402 SDK, luego reenvía con el encabezado X-PAYMENT.

Ver el x402 SDK en GitHub →

TypeScript

import fs from 'fs';
import { wrapFetchWithPayment } from '@coinbase/x402';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const fetch402 = wrapFetchWithPayment(fetch, account);

const res = await fetch402('https://x402.clearcanvas.app/v1/remove-background', {
  method: 'POST',
  headers: { 'Content-Type': 'image/png' },
  body: fs.readFileSync('photo.png'),
});

const buffer = await res.arrayBuffer();
fs.writeFileSync('result.png', Buffer.from(buffer));

Python

import os
import httpx
from x402.client import wrap_httpx   # pip install x402

client = wrap_httpx(private_key=os.environ["PRIVATE_KEY"])
resp = client.post(
    "https://x402.clearcanvas.app/v1/remove-background",
    content=open("photo.png", "rb").read(),
    headers={"Content-Type": "image/png"},
)
open("result.png", "wb").write(resp.content)

Formato de Solicitud

•Endpoint
•Body: bytes de imagen en bruto (PNG, JPEG o WebP)
•Content-Type: image/png | image/jpeg | image/webp
•Opcional: ?format=webp para salida en WebP

Formato de Respuesta

•HTTP 200 — imagen binaria (PNG o WebP)
•HTTP 402 — pago requerido (detalles x402 en el body)

Manejo de Errores

•400 — Imagen inválida (formato incorrecto, bytes mágicos no coinciden, o dimensión excedida)
•413 — Archivo demasiado grande (> 25 MB)
•415 — Content-Type no compatible
•429 — Límite de velocidad excedido (solicitudes sin pago: 30/min/IP)
•500 — Error de procesamiento (retryable: true)
•503 — Procesador temporalmente no disponible (retryable: true)

Límites y Formatos

•Tamaño máx. de archivo: 25 MB
•Dimensiones máx.: 10,000 × 10,000 px
•Entrada admitida: PNG, JPEG, WebP
•Salida: PNG (predeterminado) o WebP

Red

La API se ejecuta en Base mainnet. Los pagos se realizan en USDC real ($0,05 por imagen). Asegúrate de que tu billetera tenga USDC en Base antes de hacer solicitudes.

x402 API — Guía de Integración