MPP API Integration Guide

Everything you need to integrate background removal using the MPP payment protocol.

Quick Start

Send a POST request with your image as the raw body. The API challenges with HTTP 402 and a WWW-Authenticate: Payment header per the MPP spec.

# 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

Authentication via MPP

MPP is an open HTTP payment protocol co-launched by Stripe and Tempo. On the first request, the API returns HTTP 402 with a WWW-Authenticate: Payment challenge. Sign a pathUSD transfer on Tempo using the mppx SDK, then resend with the Authorization: Payment header.

View the mppx SDK docs →

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)

Request Format

  • •Endpoint
  • •Body: raw image bytes (PNG, JPEG, or WebP)
  • •Content-Type: image/png | image/jpeg | image/webp
  • •Optional: ?format=webp for WebP output

Response Format

  • •HTTP 200 — binary image (PNG or WebP)
  • •HTTP 402 — payment required (WWW-Authenticate: Payment challenge)

Error Handling

  • •400 — Invalid image (bad format, magic bytes mismatch, or dimension exceeded)
  • •413 — File too large (> 25 MB)
  • •415 — Unsupported Content-Type
  • •429 — Rate limit exceeded (unpaid requests: 30/min/IP)
  • •500 — Processing failed (retryable: true)
  • •503 — Processor temporarily unavailable (retryable: true)

Limits & Formats

  • •Max file size: 25 MB
  • •Max dimensions: 10,000 × 10,000 px
  • •Supported input: PNG, JPEG, WebP
  • •Output: PNG (default) or WebP

Network

The API runs on Tempo mainnet. Payments are settled in pathUSD ($0.05 per image). Ensure your Tempo wallet holds pathUSD before making requests. Use the Tempo testnet for end-to-end testing at no cost.

Ready to integrate?