MPP API 整合指南

快速入門

以原始 body 傳送含圖片的 POST 請求。API 依 MPP 規範以 HTTP 402 及 WWW-Authenticate: Payment 標頭發出挑戰。

# Step 1: discovery — returns HTTP 402 with a "Payment" challenge
curl -X POST https://mpp.clearcanvas.app/v1/remove-background \
  -H "Content-Type: image/png" \
  --data-binary @photo.png

# Step 2: paid request — attach an Authorization: Payment header
curl -X POST https://mpp.clearcanvas.app/v1/remove-background \
  -H "Content-Type: image/png" \
  -H "Authorization: Payment <mpp-credential>" \
  --data-binary @photo.png \
  --output result.png

透過 MPP 驗證

MPP 是由 Stripe 與 Tempo 共同推出的開放 HTTP 付款協議。首次請求時，API 回傳 HTTP 402 並附帶 WWW-Authenticate: Payment 挑戰。使用 mppx SDK 在 Tempo 上簽署 pathUSD 轉帳，然後附帶 Authorization: Payment 標頭重新傳送。

TypeScript

import fs from 'fs';
import { MppxClient } from 'mppx/client';

// Configure the mppx client for the Tempo crypto rail (pathUSD).
const client = new MppxClient({
  wallet: process.env.TEMPO_WALLET_PRIVATE_KEY!,
  network: 'tempo',
});

const res = await client.fetch('https://mpp.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 mpp import wrap_httpx   # pip install mpp

client = wrap_httpx(
    wallet=os.environ["TEMPO_WALLET_PRIVATE_KEY"],
    network="tempo",
)
resp = client.post(
    "https://mpp.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——需要付款（WWW-Authenticate: Payment 挑戰）

錯誤處理

• •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 在 Tempo 主網上運行。付款以 pathUSD 結算（每張圖片 $0.05）。在發出請求前，請確保您的 Tempo 錢包持有 pathUSD。您可以使用 Tempo 測試網進行端對端測試，無需任何費用。