# OverlayRemover Agent API

Pay-per-removal image cleanup for agents. No key, no account, no signup.
Each removal is one paid HTTP request, settled in-flight with the Machine
Payments Protocol (MPP, https://mpp.dev): $0.10 with a Tempo wallet, or
$0.50 by card with a Stripe Shared Payment Token (e.g. Stripe's link-cli,
where the Link account holder approves each spend in the Link app).

## Discover

    GET https://mpp.overlayremover.com/openapi.json

An OpenAPI document with endpoints, prices, payment protocols, and request
shapes.

## Set up (once)

1. Create a wallet for your agent (the key stays on your machine):

       npx mppx account create -a myagent --network mainnet

2. Fund the printed address with USDC on the Tempo network (from an exchange
   or bridge that supports Tempo). A few dollars covers dozens of removals at
   $0.10 each. Wallet options and details: https://mpp.dev/tools/wallet.md

3. That's the whole setup. No API key, no account with us, nothing to
   register. If your agent framework has built-in MPP support, it can use its
   own wallet and skip mppx entirely.

Paying by card instead: agents with Stripe's link-cli need no setup here.
Answer the 402 challenge's `stripe` method with a Shared Payment Token
(`mpp pay`); the Link account holder approves the spend in the Link app.

## Remove an overlay

    POST https://mpp.overlayremover.com/remove
    Content-Type: application/json

    {"image": "data:image/png;base64,..."}

- `image`: a data URL. PNG, JPEG, or WebP, up to 8 MB. You must own the image
  or have the right to edit it; do not use this API to remove credits or
  rights-management information from work that is not yours.
- Unpaid requests receive `402 Payment Required` with `WWW-Authenticate`
  payment challenges: Tempo mainnet (settled in USDC) and a Stripe Shared
  Payment Token card lane. Pay and retry, or use an MPP client that handles
  the challenge automatically:

    npx mppx --network mainnet -J '{"image":"data:image/png;base64,..."}' \
      https://mpp.overlayremover.com/remove

- Paid responses are JSON with an MPP receipt:

    {"format": "image/png", "download_url": "<presigned URL>", "expires_in_seconds": 900}

Typical latency is about fifteen seconds. The download URL is valid for 15
minutes. Uploads and results are deleted within 24 hours and never used for
training.

## Errors

| HTTP | code | Meaning |
|---|---|---|
| 400 | bad_request | Body is not valid JSON |
| 400 | bad_image | `image` is not a supported data URL |
| 402 | payment-required | Pay using a WWW-Authenticate challenge, then retry |
| 404 | not_found | Unknown path; see /openapi.json |
| 405 | use_post | /remove takes POST only |
| 413 | too_large | Image over 8 MB |
| 422 | cannot_edit | Declined by the safety system (photos of recognizable people most often) |
| 502 | engine_error | Upstream engine failed; you were charged, retry or contact support |
| 504 | engine_timeout | Engine exceeded 25s; retry |

## Status and versioning

Payments settle in USDC on Tempo mainnet, or by card via Stripe Shared
Payment Tokens. This API is unversioned. Breaking changes will be announced
in this document before they ship. Humans: https://overlayremover.com.
Contact: hello@overlayremover.com.