Background Removal API Documentation

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

Getting Started

Authentication Required

All processing endpoints require a valid API key in the Authorization header.

Complete Example with All Features:

curl -X POST "https://app.atarahlabs.com/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -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)

JSON API (/process)

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

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 distance - Integer values (e.g., 20): Absolute pixels (backward compatible) - Float values (e.g., 0.05): Relative to image size (0.0-1.0 recommended) - intensity: Shadow opacity (0.0-1.0) - blur: Shadow blur radius - Integer values (e.g., 15): Absolute pixels (capped at 5% of image size for performance) - Float values (e.g., 0.02): Relative to image size (capped at 0.05 = 5% max)

Examples: - "true" - Default shadow - "false" - No shadow - "true,bottom-right,20,0.5,15" - Custom shadow with 20px offset and 15px blur - "true,bottom-right,0.05,0.5,0.05" - Custom shadow with 5% relative offset and 5% relative blur (max) - "true,bottom-right,0.05,0.5,15" - Mixed: 5% relative offset with 15px absolute blur

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 YOUR_API_KEY" \
  -F "file=@your_image.jpg"

JSON API

Base64 Image Processing:

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

URL Image Processing:

curl -X POST "https://app.atarahlabs.com/process" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -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 YOUR_API_KEY" \
  -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)