Docker Gateway Integration Guide | BackgroundErase.com

This Docker integration runs a lightweight private gateway in front of the BackgroundErase API. It does not ship models and does not require a GPU. Instead, it accepts a JSON request, prepares a 1024×1024 thumbnail, calls the upstream API, receives a mask back, composites that mask onto your original image, and returns a PNG response.

Quick summary: Build the container, run it locally on localhost:8585, send JSON requests with your x-api-key header, and decode the returned base64 PNG.

Prerequisites

Docker installed and running
A BackgroundErase API token from your account dashboard

What this gateway does

Under the hood, the container:

Reads your input image
Fixes EXIF rotation
Creates a 1024×1024 JPEG thumbnail at roughly quality 85
Calls the upstream BackgroundErase API
Receives a mask response
Upscales the mask back to the original image dimensions
Composites the result onto the original image
Returns a base64 PNG in the image field

Quickstart: build and run

Clone the repository, build the container, and run it locally:

git clone https://github.com/PramaLLC/ben-api-python-docker-integration
cd ben-api-python-docker-integration
docker build -t ben-api .
docker run -p 8585:8585 ben-api

The gateway listens on: http://localhost:8585.

Important: You must include your API key on every request using the x-api-key header.

Request format

This container accepts JSON only. It does not expose a /v2 route and does not accept multipart uploads.

You can send either:

An inline base64 image
A local image path that is visible inside the container

Option A: send inline base64

First create a payload.json file like this:

{
  "image": "BASE64_DATA"
}

Then send the request:

# 1) Create payload.json with your base64 image:
# { "image": "BASE64_DATA" }

curl -X POST http://localhost:8585 \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  --data @payload.json \
  | jq -r ".image" | base64 --decode > response.png

Option B: send a local path

If you want the container to read a local file directly, bind-mount a folder when you run Docker, then post the file path as seen inside the container.

# Example: mount a local folder into /data
docker run -p 8585:8585 -v "$PWD:/data" ben-api

# Then post the path inside the container:
curl -X POST http://localhost:8585 \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "image_path": "/data/input.jpg" }' \
  | jq -r ".image" | base64 --decode > response.png

Configuration

Port: the container exposes 8585
Auth: no environment variable is required; send x-api-key on each request
Volumes: bind-mount a folder if you want to use image_path

Production notes

Run behind a reverse proxy such as Nginx with TLS enabled.
Set Docker restart policies and reasonable CPU / memory limits.
Rotate API keys regularly and store them securely.
Never hard-code API keys into container images.

Best fit: This gateway is ideal when you want a simple private wrapper around the API using JSON-only requests, especially for local infrastructure or internal services.