Guide d'intégration développeur — API Clear Canvas

Démarrage rapide

Envoyez une requête POST avec votre image comme corps brut. Aucun en-tête d'autorisation requis — l'API utilise x402 pour le paiement.

# 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

Authentification via x402

x402 est un protocole de paiement HTTP standard. Lors de la première requête, l'API renvoie HTTP 402 avec les détails de paiement. Signez un transfert USDC sur Base avec le Coinbase x402 SDK, puis renvoyez avec l'en-tête X-PAYMENT.

Voir le x402 SDK sur 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)

Format de requête

•Endpoint
•Body : octets d'image bruts (PNG, JPEG ou WebP)
•Content-Type : image/png | image/jpeg | image/webp
•Optionnel : ?format=webp pour une sortie WebP

Format de réponse

•HTTP 200 — image binaire (PNG ou WebP)
•HTTP 402 — paiement requis (détails x402 dans le body)

Gestion des erreurs

•400 — Image invalide (mauvais format, magic bytes non concordants, ou dimension dépassée)
•413 — Fichier trop volumineux (> 25 Mo)
•415 — Content-Type non supporté
•429 — Limite de débit dépassée (requêtes non payées : 30/min/IP)
•500 — Échec du traitement (retryable : true)
•503 — Processeur temporairement indisponible (retryable : true)

Limites et formats

•Taille max. du fichier : 25 Mo
•Dimensions max. : 10 000 × 10 000 px
•Entrée supportée : PNG, JPEG, WebP
•Sortie : PNG (par défaut) ou WebP

Réseau

L'API fonctionne sur Base mainnet. Les paiements sont réglés en USDC réel (0,05 $ par image). Assurez-vous que votre portefeuille contient des USDC sur Base avant d'effectuer des requêtes.

x402 API — Guide d'intégration