x402 API Integration Guide

Quick Start

Send a POST request with your image as the raw body. No auth header needed — the API uses x402 for payment.

# 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

Authentication via x402

x402 is a standard HTTP payment protocol. On the first request, the API returns HTTP 402 with payment details. Sign a USDC transfer on Base using the Coinbase x402 SDK, then resend with the X-PAYMENT header.

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)

Request Format

• •Endpoint
• •Body: raw image bytes (PNG, JPEG, or WebP)
• •Content-Type: image/png | image/jpeg | image/webp
• •Optional: ?format=webp for WebP output

Response Format

• •HTTP 200 — binary image (PNG or WebP)
• •HTTP 402 — payment required (x402 details in body)

Error Handling

• •400 — Invalid image (bad format, magic bytes mismatch, or dimension exceeded)
• •413 — File too large (> 25 MB)
• •415 — Unsupported Content-Type
• •429 — Rate limit exceeded (unpaid requests: 30/min/IP)
• •500 — Processing failed (retryable: true)
• •503 — Processor temporarily unavailable (retryable: true)

Limits & Formats

• •Max file size: 25 MB
• •Max dimensions: 10,000 × 10,000 px
• •Supported input: PNG, JPEG, WebP
• •Output: PNG (default) or WebP

Network

The API runs on Base mainnet. Payments are settled in real USDC ($0.05 per image). Ensure your wallet holds USDC on Base before making requests.