withoutbg 1.0.3

AI-powered background removal with local and cloud options

withoutbg - Python SDK

AI-powered background removal with local and cloud options.

📚 View Complete Documentation →

Installation

# Using uv (recommended)
uv add withoutbg

# Or with pip
pip install withoutbg

Don't have uv yet? Download it at astral.sh/uv - it's a fast, modern Python package installer.

Quick Start

Choose Your Model:

• See Focus Open Source Results →
• See Pro API Results →
• Compare Focus vs Pro →

from withoutbg import WithoutBG

# Local processing with Open Source model
model = WithoutBG.opensource()
result = model.remove_background("input.jpg")
result.save("output.png")

# withoutBG Pro for best quality
model = WithoutBG.api(api_key="sk_your_key")
result = model.remove_background("input.jpg")
result.save("output.png")

API Usage

Single Image Processing

from withoutbg import WithoutBG

# Initialize model once
model = WithoutBG.opensource()

# Process image
result = model.remove_background("photo.jpg")
result.save("photo-withoutbg.png")

# Process with progress callback
def progress(value):
    print(f"Progress: {value * 100:.1f}%")

result = model.remove_background("photo.jpg", progress_callback=progress)

Batch Processing

from withoutbg import WithoutBG

# Initialize model once (efficient!)
model = WithoutBG.opensource()

# Process multiple images - model is reused for all images
images = ["photo1.jpg", "photo2.jpg", "photo3.jpg"]
results = model.remove_background_batch(images, output_dir="results/")

# Or process without saving
results = model.remove_background_batch(images)
for i, result in enumerate(results):
    result.save(f"output_{i}.png")

Using withoutBG Pro

from withoutbg import WithoutBG

# Initialize API client
model = WithoutBG.api(api_key="sk_your_key")

# Process images
result = model.remove_background("input.jpg")

# Batch processing with withoutBG Pro
results = model.remove_background_batch(
    ["img1.jpg", "img2.jpg", "img3.jpg"],
    output_dir="api_results/"
)

Advanced: Direct Model Access

from withoutbg import OpenSourceModel, ProAPI

# For advanced users who need direct control
opensource_model = OpenSourceModel()
result = opensource_model.remove_background("input.jpg")

# Or with custom model paths
# Models can be downloaded from: https://huggingface.co/withoutbg/focus
model = OpenSourceModel(
    depth_model_path="/path/to/depth.onnx",
    isnet_model_path="/path/to/isnet.onnx",
    matting_model_path="/path/to/matting.onnx",
    refiner_model_path="/path/to/refiner.onnx"
)

# Direct withoutBG Pro API access
api = ProAPI(api_key="sk_your_key")
result = api.remove_background("input.jpg")
usage = api.get_usage()

CLI Usage

# Process single image
withoutbg photo.jpg

# Batch processing
withoutbg photos/ --batch --output-dir results/

# Use withoutBG Pro
withoutbg photo.jpg --api-key sk_your_key

# Specify output format
withoutbg photo.jpg --format jpg --quality 90

Features

• ✨ Local processing with Focus v1.0.0 model (free, ~320MB download)
• 🚀 withoutBG Pro for best quality results
• 📦 Batch processing support
• 🎯 Python API and CLI
• 🔧 Flexible output formats (PNG, JPEG, WebP)
• ⚡ Efficient model loading - load once, process many images

Performance

Local Model:

• First run: ~5-10 seconds (~320MB download from HuggingFace)
• CPU: ~2-5 seconds per image
• Memory: ~2GB RAM

withoutBG Pro:

• ~1-3 seconds per image (network dependent)
• No local resources needed

Configuration

Model Path Environment Variables

By default, models are downloaded from HuggingFace Hub. You can override this by setting environment variables to use local model files:

export WITHOUTBG_DEPTH_MODEL_PATH=/path/to/depth_anything_v2_vits_slim.onnx
export WITHOUTBG_ISNET_MODEL_PATH=/path/to/isnet.onnx
export WITHOUTBG_MATTING_MODEL_PATH=/path/to/focus_matting_1.0.0.onnx
export WITHOUTBG_REFINER_MODEL_PATH=/path/to/focus_refiner_1.0.0.onnx

Model Files (total ~320MB):

• ISNet segmentation: 177 MB
• Depth Anything V2: 99 MB
• Focus Matting: 27 MB
• Focus Refiner: 15 MB

This is useful for:

• Offline environments
• CI/CD pipelines
• Custom model versions
• Faster startup times (no download needed)

Documentation

• Python SDK Documentation - Complete online documentation
• Focus Model Results - See example outputs
• Pro API Results - See example outputs
• Compare Models - Focus vs Pro comparison
• Main Project README - Local documentation

Development

# Install in development mode (using uv - recommended)
uv sync --extra dev

# Or with pip
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy src/

# Format code
black src/ tests/
ruff check src/ tests/

License

Apache License 2.0 - see LICENSE