# PhotoSweat — background removal API > Remove the background from a photo and get it back on transparency, white, or any solid color. > $0.01 per image (USD). No key needed to try: 10 images/day per IP, no sign-up, no watermark. > One request in, one image out — no presign, no upload URL, no polling unless the job runs long. > Results are deleted 24 hours after they are produced. Base URL: https://photosweat.shop ## What agents should know - **There is exactly one public tool right now: `POST /api/remove-background`.** The other seven (`enhance`, `colorize`, `erase`, `upscale`, `extend`, `scan-text`, `generate`) are registered but **paused** — each returns `404 tool_paused` and costs nothing. Do not call them. - **No key needed to try it.** Anonymous calls are 10 images/day per IP. Send the request with no `Authorization` header and it just works. - **A free key raises it to 30 images/day.** Sign up at https://photosweat.shop/signup (email code, email + password, or Google), then send `Authorization: Bearer sk_free_…`. The plaintext key is shown exactly once; re-issue it from https://photosweat.shop/account. - **Beyond the free quota: $0.01 per image, sold in packs of 1000 for $10.** Prepaid credits are **self-serve**: sign in at https://photosweat.shop/account and press "买一包 1000 张"; payment runs through Stripe Checkout. Credits are deducted automatically once the daily allowance is spent, one per image, and **never expire**. They are added only when Stripe's signed webhook confirms the payment (the success page grants nothing), so allow a few seconds and reload the account page. `GET /v1/me` reports the balance as `credits`; responses that spent one carry `x-credits-left`. Photoroom charges $0.02 and remove.bg about $0.20 for the same job; the account page is also where the price is published if you would rather read it from the site. - **If a job outruns `wait`** (1–25 s, default 20) the response is `202` with `job_id` and `status_url`; the job keeps running. Poll `status_url` — do not resubmit. - **Results expire in 24 hours.** Download and store them yourself. - **The free tier is best-effort**, not an SLA. One queue is shared by everyone. - **Machine-readable contract:** https://photosweat.shop/openapi.json (OpenAPI 3.1, generated from the same table as the catalog — it never drifts). ## The call ``` POST https://photosweat.shop/api/remove-background Authorization: Bearer sk_free_… # optional; anonymous works Content-Type: image/jpeg # or multipart/form-data ``` Query parameters (all optional): | query | meaning | |---|---| | `params` | JSON object of tool params, URL-encoded (see below) | | `wait` | seconds to block waiting for the result, 1–25, default 20 | | `format=json` | return JSON with a signed `result_url` instead of the image bytes | Tool params: | param | type | default | meaning | |---|---|---|---| | `background` | `transparent` \| `white` \| `color` | `transparent` | what goes behind the subject | | `color` | `#rrggbb` | `#ffffff` | only used when `background=color` | | `format` | `png` \| `jpeg` | `png` | `jpeg` with `transparent` is rejected (400); JPEG is ~3× smaller | The canvas is the **same size as the input** — nothing is cropped or reframed. **One silent exception: if the long edge of the input is over 4096 px, the image is scaled down proportionally before processing** (5000×100 → 4096×81, 6000×4000 → 4096×2731). The output is then smaller than what you sent, and nothing in the response says so — read the dimensions of the returned image if you depend on pixel coordinates matching the input. ### Retrying safely (idempotency) Agents retry. Send an `Idempotency-Key` header on the POST (any string up to 128 characters — a UUID is fine) and a retry costs nothing and creates no second job: ``` Idempotency-Key: 7d3f0c2e-… ``` Same key + same identity (your IP, or the key's account) + same tool = **the same `job_id`**. The repeat does not charge quota and does not queue anything: if the job already finished you get its result, otherwise it waits/polls like a first call. Such a response carries `x-idempotent-replay: true`. Keys are remembered for **24 hours**; the key is bound to the first image it was used with, so use one key per image. If the first job ended `failed`, its key is released and a resend really re-runs. ### Rate A per-minute ceiling sits on top of the daily quota: **30 requests/min anonymous, 120/min per key** (`GET /v1/me` returns it as `rate_limit_per_min`). Going over returns `429 rate_limited` with `retry-after`; your daily allowance is not touched. This is a runaway-loop guard, not a pricing tier — normal batch work stays well under it. ## Examples ```bash # transparent PNG (default) — hair-level edges, real alpha channel curl -sS -X POST "https://photosweat.shop/api/remove-background" \ -H "content-type: image/jpeg" --data-binary @photo.jpg -o cutout.png # white background as JPEG (much smaller than PNG) curl -sS -X POST "https://photosweat.shop/api/remove-background?params=%7B%22background%22%3A%22white%22%2C%22format%22%3A%22jpeg%22%7D" \ -H "content-type: image/jpeg" --data-binary @photo.jpg -o white.jpg # any solid color, here #f2f2f2 curl -sS -X POST "https://photosweat.shop/api/remove-background?params=%7B%22background%22%3A%22color%22%2C%22color%22%3A%22%23f2f2f2%22%7D" \ -H "content-type: image/jpeg" --data-binary @photo.jpg -o solid.png # register once -> a free key for 30 images/day (the plaintext is shown only in this response) # two steps: 1) ask for a 6-digit code by email, 2) sign up with that code curl -s -X POST https://photosweat.shop/api/auth/email/start \ -H 'content-type: application/json' -d '{"email":"you@example.com"}' curl -s -X POST https://photosweat.shop/api/auth/signup \ -H 'content-type: application/json' \ -d '{"email":"you@example.com","password":"at-least-8-chars","code":"123456"}' # -> {"key":"sk_free_…","dailyLimit":30} # (code is required because this instance has email delivery configured; the code proves the address is yours) # with the key curl -sS -X POST "https://photosweat.shop/api/remove-background" \ -H "Authorization: Bearer sk_free_…" \ -H "content-type: image/jpeg" --data-binary @photo.jpg -o cutout.png # multipart works too (field name: image) curl -sS -X POST "https://photosweat.shop/api/remove-background" \ -F image=@photo.jpg -o cutout.png # JSON instead of bytes curl -sS -X POST "https://photosweat.shop/api/remove-background?format=json" \ -H "accept: application/json" -H "content-type: image/jpeg" --data-binary @photo.jpg # how much quota is left today curl -s https://photosweat.shop/v1/me -H "Authorization: Bearer sk_free_…" # anonymous works too (reports this IP's ledger; a bad key is 401, never a silent fallback) curl -s https://photosweat.shop/v1/me ``` ## Responses - `200` — the result image bytes (`image/png` or `image/jpeg`), with `x-job-id`, `x-quota-limit`, `x-quota-used`, `x-quota-remaining`. - With `Accept: application/json` or `format=json`: `{job_id, status, tool, params, result_url, original_url}`. - `202` — still running: `{job_id, status:"queued", status_url, retry_after}`. Not a failure; the quota unit is not refunded because the job is still going. ## Auth and quota | who | per day | how | |---|---|---| | anonymous | 10 images per IP | no header | | free key | 30 images | `Authorization: Bearer sk_free_…` | | signed in on the website | 200 images (anti-script ceiling, not a paywall) | browser session | | paid | after the daily allowance runs out | prepaid credits: $10 = 1000 images, self-serve at https://photosweat.shop/account, deducted one per image, never expire | Credits are spent **only after** your daily allowance is used up, so a free key never burns paid images while it still has free ones left. `GET /v1/me` returns `credits` (0 when you have none); every response that spent a credit carries `x-credits-left`. A failed job refunds the credit. Refunds follow the charge, not the clock: a job that was charged from the daily allowance gives the unit back to **that day's** allowance (fail at 00:01 for a job created at 23:59 and yesterday's ledger gets it, today's does not), and a job charged from credits gives the credit back. This holds whether the failure comes back inside the request (`502`) or later, after the `202` — the unit is only kept for jobs that reach `done`. All limits reset at **00:00 Beijing time (UTC+8)**. One IP shares one ledger across `/api/remove-background` and `/api/presign`, so mixing endpoints does not multiply the quota. **The anonymous ledger is keyed on the calling IP, not on a device.** Everyone behind the same NAT (one office, one phone carrier gateway, one CI runner pool) draws from the same 10/day. A `429` `quota_exhausted` may therefore be someone else's usage, not yours. Send a free key (`Authorization: Bearer sk_free_…`) and the ledger becomes yours alone. ## Errors Every error body is JSON with two fields you can rely on: - **`code`** — the machine contract. Same situation, same code, forever. **Branch on this.** - **`error`** — one English sentence for a human. The wording may change; never string-match it. Where they help, extras are attached: `hint` (what to do next), `details` (per-field validation failures — `bad_param` only, each entry reads `field: what is wrong`), `tool`, `job_id`, and for `quota_exhausted` also `limit` / `used` / `kind` plus links to `/signup`, `/login` and `/account`. | HTTP | `code` | meaning | |---|---|---| | 400 | `bad_param` | a tool param has a bad value or a bad combination; `details` names the field (e.g. `format` when `background=transparent` and `format=jpeg`) | | 400 | `bad_json` | `params` is not valid JSON | | 400 | `bad_request` | the body could not be read (malformed multipart, broken boundary) | | 400 | `missing_image` | no image bytes were sent | | 400 | `missing_mask` / `bad_mask` | the tool needs a PNG mask (`white` = the area to process), and it was missing or not a PNG | | 400 | `no_input` | that tool takes no input image; it is not callable through this route | | 401 | `unauthorized` | the key is wrong or revoked, or no key was sent while anonymous access is closed. A bad key never falls back to anonymous | | 404 | `unknown_tool` | no such tool; `GET /api/tools` lists what exists | | 404 | `tool_paused` | the tool exists but is not open yet — costs nothing | | 404 | `job_not_found` | no job with that id | | 410 | `job_expired` | the result was deleted after 24 hours | | 413 | `image_too_large` | the image is over 10 MB | | 415 | `unsupported_media_type` | not JPEG / PNG / WebP (decided by magic bytes, not by Content-Type) | | 429 | `quota_exhausted` | today's free quota is gone; register, wait for midnight, or pay. Body carries `limit`, `used`, `kind`, `pricePerImageUsd` and the links named above | | 429 | `rate_limited` | more than the per-minute ceiling (30/min anonymous, 120/min per key). `retry-after` says when to come back; **this is not a quota problem** — the daily allowance is untouched | | 500 | `internal_error` | the job could not be created; the quota unit was refunded | | 502 | `processing_failed` | the job failed; the quota unit was refunded | | 502 | `storage_error` | storing the image failed; the quota unit was refunded | | 503 | `capacity_full` | the shared anonymous channel is full today — not your fault and not your quota | | 503 | `service_unavailable` | our side is temporarily down; nothing was charged | Retries, by status: | status | retry? | |---|---| | 400 / 401 / 404 / 410 / 413 / 415 | **No.** The request itself is wrong; retrying sends the same failure and burns nothing. | | 429 | **Wait.** Read `code` first: `rate_limited` clears in the seconds named by `retry-after`; `quota_exhausted` only resets at 00:00 UTC+8. Do not hammer either | | 500 / 502 | **Yes**, this is our side. Exponential backoff from 2 s, 3 attempts max. The quota unit was refunded. `x-job-id` names the attempt you can correlate. | | 503 | **Yes**, with backoff from 5 s (`capacity_full`: the shared free channel is saturated; `service_unavailable`: a dependency is down). Neither charges you. | | 202 | Not an error. Poll `status_url` every 2–3 s — do not resubmit the image. | ## Migrating from remove.bg remove.bg's standalone site is being shut down on **2026-12-01** and folded into Canva, so anything pointing at `api.remove.bg` needs a new home. Two things before you port: - **No watermark and no "preview" trick.** The bytes are the final image with a real alpha channel; no credit-per-download, no `X-Type: preview`, no 0.25 MP cap on the free tier. - **The request shape differs.** remove.bg wants `POST /v1/removebg` with a `size` enum; here it is `POST /api/remove-background` with the raw bytes as the body and no `size` parameter. ```bash # before (remove.bg) curl -s -X POST https://api.remove.bg/v1.0/removebg \ -H "X-Api-Key: $REMOVE_BG_KEY" -F image_file=@photo.jpg -F size=auto -o nobg.png # after (this service; the key is optional, anonymous works) curl -s -X POST "https://photosweat.shop/api/remove-background" \ -H "Authorization: Bearer $PHOTO_KEY" \ -H "content-type: image/jpeg" --data-binary @photo.jpg -o nobg.png ``` Need white instead of transparency? Add `params={"background":"white"}` — no second call. Moving a whole codebase over? https://photosweat.shop/migrate/remove-bg has the field-by-field mapping, the pricing comparison (dated, sourced), and the refund rules — a page for humans; this file stays the contract. ## Machine-readable - `https://photosweat.shop/api/tools` — runtime catalog: slug, status, price, params. Start here. - `https://photosweat.shop/api/status` — live health (database, storage, scheduler heartbeat, last hour's job counts). Returns `200` when healthy, `503` when degraded — check it before blaming your own request. - `https://photosweat.shop/openapi.json` — OpenAPI 3.1, generated from the same capability table. - `https://photosweat.shop/changelog` — every change to this API, newest first, plus the deprecation policy (90-day notice for anything breaking). - `https://photosweat.shop/api/capabilities` — every capability with parameter ranges (bilingual). - `https://photosweat.shop/.well-known/mcp.json` — service card for MCP hosts. - `https://photosweat.shop/mcp` — the MCP endpoint itself (Streamable HTTP, stateless). - Every response carries a `Link` header: `rel="service-desc"` (OpenAPI), `rel="describedby"` (this file), `rel="alternate"` (the MCP card). ## Contract stability - The `code` field of an error is the machine contract: codes are **only ever added**. The human-readable `error` sentence may be reworded at any time — never match it. - Anything additive (a new optional param, a new response field, a loosened limit) can ship at any time; ignore fields you do not know. - Anything breaking (removing a route, changing what a required param means, tightening a limit) is announced on https://photosweat.shop/changelog at least **90 days** ahead, with both versions live in between. During that window the deprecated route answers normally, and every response from it carries `Sunset: ` plus `Link: ; rel="successor-version"` when a replacement exists. - Prices never change retroactively: prepaid credits already bought are never repriced or expired. ## MCP If your host speaks MCP (Model Context Protocol), you do not need to read the rest: point it at ``` https://photosweat.shop/mcp ``` Streamable HTTP, **stateless** (`POST` only — no session id, no SSE stream, no DELETE). One tool: - `remove_background` — arguments `image_base64` **or** `image_url`, plus `background` (`transparent` | `white` | `color`), `color` (`#rrggbb`), `format` (`png` | `jpeg`). The result is an MCP **image content block** at the input's pixel size (same 4096 px long-edge clamp as REST: a bigger input comes back smaller). - Auth is optional here too: anonymous is 10 images/day per IP, `Authorization: Bearer sk_free_…` raises it to 30/day. Same ledger as the REST endpoints. The exact numbers for your key are in the tool result text and in `GET /v1/me` — trust those over the figures written here. Hand-rolled call, if you want to see the wire format: ```bash curl -sS -X POST https://photosweat.shop/mcp \ -H 'content-type: application/json' \ -H 'accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' curl -sS -X POST https://photosweat.shop/mcp \ -H 'content-type: application/json' \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{ "name":"remove_background", "arguments":{"image_url":"https://example.com/photo.jpg","background":"white","format":"jpeg"}}}' ``` A local stdio MCP server also lives in the repository under `web/mcp/`; point it at `PHOTO_API=https://photosweat.shop`. ## Limits - Input: JPEG / PNG / WebP, max 10 MB, long edge clamped to 4096 px (downscale before sending large photos — it saves upload time and gives the same result as letting us clamp it). - Output: PNG (lossless, `zlib` level 3) or JPEG q95, at the input's pixel size after that clamp — i.e. the same size as the input unless the input's long edge was over 4096 px. - 24-hour retention on both the original and the result. ## Optional - [API keys](https://photosweat.shop/apikey): docs + usage check; [sign up](https://photosweat.shop/signup) for a key - [Status](https://photosweat.shop/status): live health, human-readable (same data as `/api/status`) - [Changelog](https://photosweat.shop/changelog): changes + deprecation policy - [Background removal](https://photosweat.shop/remove-bg): human-facing tool - [OpenAPI 3.1](https://photosweat.shop/openapi.json) - [Capability list](https://photosweat.shop/api/capabilities): JSON