Background Removal Container

This guide covers deployment and usage of the EyeQ Background Removal Docker container. The container provides a GPU-accelerated HTTP API for removing backgrounds from images.

Workflow overview

The workflow for using the container is:

1. Deploy the Docker image and run the container with GPU access
2. Apply your license key to activate the container
3. Submit images for processing and track their status
4. Download processed images when complete

Requirements and deployment

Requirements

This container has been tested on AWS G6.4xlarge instances using NVIDIA T4 GPUs, NVidia 5090 mobile GPU, and NVIDIA A100 GPUs. Other GPUs are expected to work but have not been tested.

• NVidia GPU with at least 16GB of VRAM
• CUDA version 12.8 and NVIDIA drivers installed and configured
• Docker installed on your machine, configured to access the GPU
• EyeQ license key

Import the Docker image

docker load --input eyeq_bgr_372_0.tar

This loads the Docker image from the tar archive into your local Docker engine.

Run the container

docker run --gpus all -p 8000:8000 eyeq_bgr_372_0

• --gpus all: Makes all available GPUs accessible to the container
• -p 8000:8000: Maps port 8000 from the container to port 8000 on your host machine

Activate the license

Once the container is running, activate it with your EyeQ license key by sending a GET request to the /Authorize endpoint:

curl -X GET http://localhost:8000/Authorize/{license_key}

Replace {license_key} with your actual EyeQ license key. This is required once per container instance. After activation, the container is ready to process images.

API reference

The container provides a REST API for image processing operations. All endpoints return JSON responses unless otherwise specified. The basic usage pattern is:

1. Submit an image for processing using /SubmitImage
2. Poll the status using /CheckImage/{process_id} until you receive "status":"completed"
3. Download the processed image using /DownloadImage/{process_id}
4. Remove the processed image from the container using /RemoveImage/{process_id}

Authorize

GET /Authorize/{license_key}

Apply a license key to the current container instance. This is required once per container instance — calls to upload or process images will fail until this is performed.

Parameters

Responses

{
  "status": "Licensed|Unlicensed",
  "message": "licensing_message",
  "licensed org": "org_name",
  "expiration date": "2026-11"
}

Status

GET /Status

Check container licensing status and model version.

Responses

{
  "status": "Licensed|Unlicensed",
  "message": "status_message",
  "model_version": "model_version",
  "licensed org": "org_name",
  "expiration date": "2026-11-01T00:00:00+00:00"
}

Submit image

POST /SubmitImage

Upload an image for background removal processing. Example request:

curl -X 'POST' \
  'http://localhost:8000/SubmitImage?preprocessing=true&postprocessing=true' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@photo.jpg;type=image/jpeg' \
  -F 'mode=portrait' \
  -F 'preprocessing_config='

Parameters

Responses

{
  "status": "processing",
  "process_id": "uuid-string",
  "mode": "portrait|general",
  "preprocessing_enabled": "true|false",
  "message": "Image processing started"
}

The process_id is a UUID that identifies this processing job in all subsequent API calls.

Check image status

GET /CheckImage/{process_id}

Check the status of a processing job.

Parameters

Responses

{
  "status": "queued|processing|completed|failed",
  "original_name": "filename.jpg",
  "mode": "portrait|general",
  "processing_time": 1.23,
  "error": "error string"
}

The processing_time and error fields are only present for completed and failed statuses respectively.

Download image

GET /DownloadImage/{process_id}

Download the processed image with the background removed.

Parameters

Responses

Remove image

DELETE /RemoveImage/{process_id}

Delete a processed image after downloading it.

Parameters

Responses

{
  "status": "deleted",
  "process_id": "uuid-string",
  "files_deleted": 2,
  "previous_status": "processing|completed|failed"
}

Complete example

This script submits an image for background removal, polls until processing is complete, then downloads the result:

#!/bin/bash

INPUT=${1:-photo.jpg}
OUTPUT=${2:-photo_nobg.png}

if [ ! -f "$INPUT" ]; then
    echo "File $INPUT not found"
    exit 1
fi

# Submit the image
process_id=$(curl -s -X POST \
  "http://localhost:8000/SubmitImage?preprocessing=true" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@${INPUT};type=image/jpeg" \
  -F "mode=portrait" | jq -r '.process_id')
echo "Submitted: ${process_id}"

# Poll until complete
while true; do
    status=$(curl -s -X GET "http://localhost:8000/CheckImage/${process_id}" | jq -r '.status')
    echo "Status: ${status}"
    if [ "${status}" == "completed" ]; then
        break
    elif [ "${status}" == "failed" ]; then
        echo "Processing failed"
        exit 1
    fi
    sleep 1
done

# Download the result
curl -s -X GET "http://localhost:8000/DownloadImage/${process_id}" -o "${OUTPUT}"
echo "Saved to: ${OUTPUT}"

# Clean up
curl -s -X DELETE "http://localhost:8000/RemoveImage/${process_id}" > /dev/null
echo "Cleaned up"