Background Removal API Documentation

A professional-grade background removal API with advanced AI-powered processing.

Getting Started

Demo API Key

Demo Key: qz18vR4PaZKNHPvtLLdS6hL9ySiLxB1x

Complete Example with All Features:

curl -X POST "https://app.atarahlabs.com/upload" \
  -H "Authorization: Bearer qz18vR4PaZKNHPvtLLdS6hL9ySiLxB1x" \
  -F "file=@your_image.jpg" \
  -F "background_color=white" \
  -F "shadow_config=true" \
  -F "output_type=all" \
  --max-time 300 > response.json

jq -r '.result_image_base64' response.json | base64 -d > output.png

API Reference

Endpoints

Endpoint	Method	Description
`/upload`	POST	File upload API for background removal
`/process`	POST	JSON API for background removal (base64 or URL)
`/health`	GET	Health check (no auth required)

Primary Domain: https://app.atarahlabs.com
Fallback Domains: - Upload: https://bg-remover--upload.modal.run - Process: https://bg-remover--process.modal.run - Health: https://bg-remover--health.modal.run

Authentication

All processing endpoints require an API key in the Authorization header:

Authorization: Bearer your_api_key_here

Request Parameters

File Upload API (`/upload`)

file: Image file (multipart/form-data)
background_color: Background color (optional)
shadow_config: Shadow configuration (optional)
return_format: Output format (optional, default: png)
output_type: What to return (optional, default: both) - "both", "image", "mask", "shadow", "components", or "all"

JSON API (`/process`)

image: Base64 encoded image data (optional, use either this or image_url)
image_url: URL to image file (optional, use either this or image)
background_color: Background color (optional)
shadow_config: Shadow configuration (optional)
return_format: Output format (optional, default: png)
output_type: What to return (optional, default: both) - "both", "image", "mask", "shadow", "components", or "all"

Output Types

Control what the API returns for flexible post-processing:

Type	Returns	Use Case
`both`	Result image + mask	Complete processing (default)
`image`	Result image only	When you only need the final image
`mask`	Segmentation mask only	For custom background application
`shadow`	Shadow layer only	For offline shadow compositing
`components`	Mask + shadow (no image)	Fast processing for compositing workflows
`all`	Image + mask + shadow	Maximum flexibility

Background Colors

Hex codes: #FFFFFF, #FF6B6B, #E8F4FD
RGB values: 255,255,255 (comma-separated)
Color names: white, red, blue, lightblue, lightgray

Shadow Configuration

Format: "enabled,direction,size,intensity,blur"

Parameters: - enabled: true/false - direction: bottom-right, bottom-left, top-right, top-left, bottom, top, left, right - size: Shadow offset (0-100 pixels) - intensity: Shadow opacity (0.0-1.0) - blur: Shadow blur radius (0-50 pixels)

Examples: - "true" - Default shadow - "false" - No shadow - "true,bottom-right,20,0.5,15" - Custom shadow

Response Format

{
  "success": true,
  "result_image_base64": "base64_encoded_result",
  "mask_image_base64": "base64_encoded_mask",
  "shadow_image_base64": "base64_encoded_shadow",
  "width": 1024,
  "height": 1024,
  "format": "png",
  "has_background": true,
  "has_shadow": true,
  "filename": "input.jpg",
  "user": "Demo User"
}

Response Fields: - result_image_base64: Final processed image (when output_type includes 'image') - mask_image_base64: Segmentation mask (when output_type includes 'mask')
- shadow_image_base64: Shadow layer for offline compositing (when output_type includes 'shadow' and shadows enabled) - width/height: Image dimensions - has_background: Whether a background color was applied - has_shadow: Whether shadow effects are enabled

Output Field Presence by Type: - output_type=both: result_image_base64 + mask_image_base64 (default) - output_type=image: Only result_image_base64 - output_type=mask: Only mask_image_base64 - output_type=shadow: Only shadow_image_base64 (when shadows enabled) - output_type=components: Only mask_image_base64 + shadow_image_base64 (fast processing) - output_type=all: result_image_base64 + mask_image_base64 + shadow_image_base64

cURL Examples

File Upload API

Complete Example (Recommended):

curl -X POST "https://app.atarahlabs.com/upload" \
  -H "Authorization: Bearer qz18vR4PaZKNHPvtLLdS6hL9ySiLxB1x" \
  -F "file=@your_image.jpg" \
  -F "background_color=white" \
  -F "shadow_config=true" \
  -F "output_type=all" \
  --max-time 300 > response.json

jq -r '.result_image_base64' response.json | base64 -d > output.png

Basic Background Removal:

curl -X POST "https://app.atarahlabs.com/upload" \
  -H "Authorization: Bearer qz18vR4PaZKNHPvtLLdS6hL9ySiLxB1x" \
  -F "file=@your_image.jpg"

JSON API

Base64 Image Processing:

curl -X POST "https://app.atarahlabs.com/process" \
  -H "Authorization: Bearer qz18vR4PaZKNHPvtLLdS6hL9ySiLxB1x" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "base64_encoded_image_data",
    "background_color": "white",
    "shadow_config": "true,bottom-right,20,0.5,15",
    "output_type": "all"
  }'

URL Image Processing:

curl -X POST "https://app.atarahlabs.com/process" \
  -H "Authorization: Bearer qz18vR4PaZKNHPvtLLdS6hL9ySiLxB1x" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/image.jpg",
    "background_color": "white",
    "output_type": "both"
  }'

Return Only Mask:

curl -X POST "https://app.atarahlabs.com/process" \
  -H "Authorization: Bearer qz18vR4PaZKNHPvtLLdS6hL9ySiLxB1x" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/image.jpg",
    "output_type": "mask"
  }'

Compositing Logic

Given:
- I_orig: Original image (RGB, 0-255)
- M: Mask (grayscale, 0-255)
- S: Shadow (RGBA, 0-255)
- B: Background color (RGB tuple, 0-255)

Step 1: Normalize mask
M_norm = M / 255.0

Step 2: Create background array
bg_array = full_array_of_background_color

Step 3: Apply shadow to background (if shadow exists)
shadow_alpha = S[:,:,3] / 255.0
bg_array = bg_array * (1 - shadow_alpha)

Step 4: Blend foreground and background
result = I_orig * M_norm + bg_array * (1 - M_norm)