Documentation

API Reference

SimpleRemove provides a simple REST API for background removal and canvas normalization.

Base URL

https://api.simpleremove.com/v1

Authentication: Bearer Token via Authorization header

Content-Type: multipart/form-data

POST/remove-background

Remove the background from an image. Optionally normalise the output to a fixed canvas size with padding.

Request Parameters

Parameter	Type	Required	Description
image	file	Yes	PNG, JPG, or WebP. Max 10 MB.
canvas_width	integer	No	Output canvas width in px. Requires canvas_height.
canvas_height	integer	No	Output canvas height in px. Requires canvas_width.
padding_side	integer	No	Left + right padding in px. Default: 0.
padding_bottom	integer	No	Bottom padding in px — subject sits above this. Default: 0.
padding_top	integer	No	Minimum top padding in px. Default: 0.

Responses

200PNG image (binary)

413{ "error": "file_too_large" }

415{ "error": "unsupported_format" }

422{ "error": "processing_failed" }

429{ "error": "rate_limit_exceeded" }

Example — simple removal

curl -X POST https://api.simpleremove.com/v1/remove-background \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@product.jpg" \
  --output result.png

Example — with canvas normalization

curl -X POST https://api.simpleremove.com/v1/remove-background \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@product.jpg" \
  -F "canvas_width=1000" \
  -F "canvas_height=1000" \
  -F "padding_bottom=80" \
  -F "padding_side=40" \
  --output result.png

GET/health

Check whether the API and the underlying AI service are operational.

200{ "status": "ok", "python_service": "ok" }

503{ "status": "degraded", "python_service": "unavailable" }

Example

curl https://api.simpleremove.com/v1/health \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "status": "ok",
  "python_service": "ok"
}

Error Codes

Code	HTTP	Description
processing_failed	422	The AI model could not process the image.
file_too_large	413	The uploaded file exceeds the 10 MB limit.
unsupported_format	415	Only PNG, JPG, and WebP are supported.
rate_limit_exceeded	429	Too many requests. Retry after the limit resets.

Limits

Max file size

10 MB

Supported formats

PNG, JPG, WebP

Rate limit

60 req / min

Max canvas size

5000 × 5000 px