開發者整合指南 — Clear Canvas 背景去除 API

快速入門

以原始 body 傳送含圖片的 POST 請求。無需授權標頭——API 使用 x402 進行付款。

# 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

透過 x402 驗證

x402 是標準 HTTP 付款協議。首次請求時，API 返回 HTTP 402 並附付款詳情。使用 Coinbase x402 SDK 在 Base 上簽署 USDC 轉帳，然後附帶 X-PAYMENT 標頭重新傳送。

在 GitHub 上查看 x402 SDK →

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)

請求格式

•端點
•Body：原始圖片位元組（PNG、JPEG 或 WebP）
•Content-Type：image/png | image/jpeg | image/webp
•可選：?format=webp 輸出 WebP 格式

回應格式

•HTTP 200——二進位圖片（PNG 或 WebP）
•HTTP 402——需要付款（x402 詳情在 body 中）

錯誤處理

•400——無效圖片（格式錯誤、magic bytes 不符或超出尺寸限制）
•413——檔案過大（> 25 MB）
•415——不支援的 Content-Type
•429——超過速率限制（未付費請求：每分鐘 30 次/IP）
•500——處理失敗（retryable: true）
•503——處理器暫時不可用（retryable: true）

限制與格式

•最大檔案大小：25 MB
•最大尺寸：10,000 × 10,000 像素
•支援輸入：PNG、JPEG、WebP
•輸出：PNG（預設）或 WebP

網路

API 在 Base 主網上運行。付款以真實 USDC 結算（每張圖片 $0.05）。在發出請求前，請確保您的錢包在 Base 上持有 USDC。

x402 API 整合指南