x402 API — Integrationsleitfaden

Schnellstart

Senden Sie eine POST-Anfrage mit Ihrem Bild als Rohinhalt. Kein Autorisierungsheader erforderlich — die API verwendet x402 für die Zahlung.

# 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

Authentifizierung via x402

x402 ist ein Standard-HTTP-Zahlungsprotokoll. Bei der ersten Anfrage gibt die API HTTP 402 mit Zahlungsdetails zurück. Signieren Sie eine USDC-Überweisung auf Base mit dem Coinbase x402 SDK und senden Sie die Anfrage mit dem X-PAYMENT-Header erneut.

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)

Anfrageformat

• •Endpunkt
• •Body: rohe Bildbytes (PNG, JPEG oder WebP)
• •Content-Type: image/png | image/jpeg | image/webp
• •Optional: ?format=webp für WebP-Ausgabe

Antwortformat

• •HTTP 200 — Binärbild (PNG oder WebP)
• •HTTP 402 — Zahlung erforderlich (x402-Details im Body)

Fehlerbehandlung

• •400 — Ungültiges Bild (falsches Format, Magic-Bytes stimmen nicht überein, oder Abmessung überschritten)
• •413 — Datei zu groß (> 25 MB)
• •415 — Nicht unterstützter Content-Type
• •429 — Rate-Limit überschritten (unbezahlte Anfragen: 30/min/IP)
• •500 — Verarbeitung fehlgeschlagen (retryable: true)
• •503 — Prozessor vorübergehend nicht verfügbar (retryable: true)

Limits und Formate

• •Max. Dateigröße: 25 MB
• •Max. Abmessungen: 10.000 × 10.000 px
• •Unterstützte Eingabe: PNG, JPEG, WebP
• •Ausgabe: PNG (Standard) oder WebP

Netzwerk

Die API läuft im Base-Mainnet. Zahlungen werden in echtem USDC abgewickelt ($0,05 pro Bild). Stellen Sie sicher, dass Ihre Wallet USDC auf Base enthält, bevor Sie Anfragen stellen.