API Reference

API Reference

The service exposes a single endpoint, POST /remove-bg. Both apps — service.app (IS-Net) and service.app_u2net (U²-Net) — implement it with the same request and response format. The only difference is the S-Processing-Device header, which only the IS-Net app sends.

POST /remove-bg

Removes the background of the uploaded image and returns it as a PNG with transparency.

Request

• Content type: multipart/form-data
• Fields:

Field	Type	Required	Description
file	file	yes	The source image. It is read into memory and decoded with Pillow / imageio (for example JPEG or PNG).

Example:

curl -X POST \
  -F "file=@shoe.jpg" \
  http://localhost:8000/remove-bg \
  --output shoe.png

Success response

• Status: 200 OK
• Content type: image/png
• Body: the processed image, streamed. It is an RGBA image with the same width and height as the input; background pixels are transparent.

Header	Sent by	Description
S-Processing-Time	both apps	Time spent processing the request, in seconds (float as string).
S-Processing-Server	both apps	Server version tag, currently V1.
S-Processing-Device	IS-Net app	Device used for inference: cuda or cpu.

Error response

If anything fails (for example an unreadable or unsupported image, or an inference error), the service logs the exception and returns:

• Status: 400 Bad Request
• Content type: application/json

{ "error": "<exception message>" }

If the file field is missing entirely, FastAPI's own request validation responds before the handler runs, with status 422 and a validation error body.

What happens inside

IS-Net app (service/app.py)

1. Reads the upload into an in-memory buffer.
2. Decodes the image and resizes it to 1024 × 1024 for the network.
3. Normalizes it and runs ISNetDIS to predict a mask.
4. Resizes the mask back to the original size and normalizes it to 0–255.
5. Composites the original image over a transparent RGBA canvas using the mask.
6. Streams the result as PNG.

U²-Net app (service/app_u2net.py)

1. Opens the upload with Pillow.
2. Rescales to 320 × 320 and runs U2NET(3, 1) to predict a mask.
3. Repeats the masking pass 4 times on the previous output to refine it.
4. Resizes back to the original size and composites over a transparent canvas.
5. Streams the result as PNG.

See Models for details.

Interactive documentation

FastAPI serves Swagger UI at /docs and ReDoc at /redoc, for example http://localhost:8000/docs. The route is declared with response_class=HTMLResponse, so the generated schema lists text/html as the response type, although the real response is image/png.

Related

• Client Examples
• Models
• Deployment
• FAQ