withoutbg - Python SDK (Developer Guide, Focus v1.0.0)#
AI-powered background removal with local and cloud options
Latest: The new Focus v1.0.0 model is now the default for local processing. It delivers markedly better edges, hair/fur handling, and generalization than the legacy Snap model.
Install#
Installation
pip install withoutbgQuick Start#
Local (Focus v1.0.0, free)#
Local Processing with Focus
from withoutbg import remove_background
img = remove_background("input.jpg") # uses Focus locally
img.save("output.png") # RGBA with transparencyCloud (best quality)#
Cloud API Processing
from withoutbg import remove_background
img = remove_background("input.jpg", api_key="sk_your_api_key")
img.save("output.png")CLI#
Command Line Interface
# Local
withoutbg image.jpg
# Cloud
withoutbg image.jpg --api-key sk_your_api_keyAPI Reference#
When using the cloud API (api_key parameter), the SDK calls these endpoints:
- Background Removal: Binary and Base64 variants
- Alpha Matte Extraction: Binary and Base64 variants for advanced compositing
- Credits Management: GET /available-credit for usage tracking
For detailed endpoint specifications, error codes, rate limits, and advanced options, see the API Documentation.
Python API
Python API#
remove_background()#
Removes the background from a single image.
input_image: path-like or file-like image input.api_key(optional): if provided, routes to the cloud API; otherwise uses local Focus.- Returns:
PIL.Image.Imagein RGBA (transparent background).
Example#
Remove Background Example
from withoutbg import remove_background
result = remove_background("portrait.jpg") # Local Focus
result.save("portrait-no-bg.png")remove_background_batch()#
Batch removal.
image_paths: list of input files.output_dir(optional): write processed images to this directory.api_key(optional): use cloud API for all.- Returns: list of results (e.g., saved file paths or
PIL.Image.Imageobjects, depending on integration).
Example#
Batch Processing Example
from withoutbg import remove_background_batch
results = remove_background_batch(
["img1.jpg", "img2.jpg"],
output_dir="results/" # files written here
)Configuration#
API key (cloud)#
Environment Variable Setup
export WITHOUTBG_API_KEY="sk_your_api_key"Or pass per call: remove_background(..., api_key="sk_your_api_key").
Input/Output#
- Inputs: JPG/PNG/WebP (typical).
- Outputs: Prefer PNG/WebP to retain transparency.
- Compositing: Use the alpha channel as mask.
Compositing Example
from PIL import Image
import withoutbg
fg = withoutbg.remove_background("subject.jpg", api_key="sk_your_api_key") # or local
bg = Image.open("background.jpg")
bg.paste(fg, (0, 0), fg) # alpha used as mask
bg.save("composite.png")When to use which mode?#
| Mode | Quality | Cost | Runs | Best for |
|---|---|---|---|---|
| Focus (local) | Excellent (new default) | Free | Your machine | Scripts, privacy, offline usage |
| Cloud API | Highest (production) | Pay-per-use | Managed cloud | Hair/fur, thin edges, consistency |
CLI Reference (short)#
CLI Usage
# Single image
withoutbg photo.jpg
withoutbg photo.jpg --output result.png
withoutbg photo.jpg --format webp --quality 90
# Cloud API
export WITHOUTBG_API_KEY="sk_your_api_key"
withoutbg photo.jpg --use-api
# or:
withoutbg photo.jpg --api-key sk_your_api_key
# Batch
withoutbg photos/ --batch --output-dir results/
withoutbg photos/ --batch --use-api --output-dir results/Usage Analytics (Cloud)#
Usage Analytics
from withoutbg.api import StudioAPI
api = StudioAPI(api_key="sk_your_api_key")
usage = api.get_usage() # Calls GET /available-credit
print(f"Credits: {usage['credit']}, Expires: {usage['expiration_date']}")For detailed credit management, see: Credits API Documentation
Advanced: Direct API Access#
The SDK uses the cloud API under the hood. For advanced use cases like:
- Custom request/response handling
- Different programming languages
- Serverless environments
- Direct endpoint integration
See the API Documentation for:
- Background Removal (Binary) — Direct PNG output for server workflows
- Background Removal (Base64) — JSON responses for browser/serverless apps
- Alpha Matte Binary — Separate alpha masks for advanced compositing
- Alpha Matte Base64 — Alpha matte in base64 encoding
The SDK is a convenience wrapper; all functionality is available through the REST API.
Models (Hugging Face)#
- Latest (recommended): Focus v1.0.0 — withoutbg/focus
- Legacy: Snap v0.1.0 — withoutbg/snap (kept for compatibility)
Focus uses a 4-stage pipeline (Depth → ISNet → Matting → Refiner) and typically yields 30–40% better edge/detail fidelity than the previous generation.
Commercial & Docs#
- API (pay-per-use): best quality, scalable infra, high availability
- Docs: Full API reference at withoutbg.com/documentation
- Try it: withoutbg.com/remove-background
Support#
- Issues: GitHub Issues