Guia de Integração para Desenvolvedores — API do Clear Canvas

Início Rápido

Envie uma requisição POST com sua imagem como corpo bruto. Sem cabeçalho de autorização — a API usa x402 para pagamento.

# 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

Autenticação via x402

x402 é um protocolo de pagamento HTTP padrão. Na primeira requisição, a API retorna HTTP 402 com detalhes de pagamento. Assine uma transferência USDC na Base usando o Coinbase x402 SDK e reenvie com o cabeçalho X-PAYMENT.

Ver o x402 SDK no 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 da Requisição

•Endpoint
•Body: bytes brutos da imagem (PNG, JPEG ou WebP)
•Content-Type: image/png | image/jpeg | image/webp
•Opcional: ?format=webp para saída em WebP

Formato da Resposta

•HTTP 200 — imagem binária (PNG ou WebP)
•HTTP 402 — pagamento necessário (detalhes x402 no body)

Tratamento de Erros

•400 — Imagem inválida (formato incorreto, magic bytes não coincidentes, ou dimensão excedida)
•413 — Arquivo muito grande (> 25 MB)
•415 — Content-Type não suportado
•429 — Limite de requisições excedido (requisições não pagas: 30/min/IP)
•500 — Falha no processamento (retryable: true)
•503 — Processador temporariamente indisponível (retryable: true)

Limites e Formatos

•Tamanho máx. do arquivo: 25 MB
•Dimensões máx.: 10.000 × 10.000 px
•Entrada suportada: PNG, JPEG, WebP
•Saída: PNG (padrão) ou WebP

Rede

A API roda na mainnet da Base. Os pagamentos são feitos em USDC real ($0,05 por imagem). Certifique-se de que sua carteira tem USDC na Base antes de fazer requisições.

x402 API — Guia de Integração