Python SDK

pip install poofbg

from poofbg import Poof

# Initialize the client
client = Poof(api_key="poof_your_api_key")

# Remove background from a file
result = client.remove("photo.jpg")
result.save("result.png")

import os
from poofbg import Poof

# Option 1: Pass directly (not recommended for production)
client = Poof(api_key="poof_your_api_key")

# Option 2: Use environment variable (recommended)
# export POOF_API_KEY=poof_your_api_key
client = Poof()  # Reads from POOF_API_KEY

result = client.remove("photo.jpg")
result.save("result.png")

with open("photo.jpg", "rb") as f:
    image_bytes = f.read()

result = client.remove(image_bytes)

# Access the result as bytes
png_bytes = result.data

# Or save directly
result.save("result.png")

import requests

image_url = "https://example.com/photo.jpg"
response = requests.get(image_url)

result = client.remove(response.content)
result.save("result.png")

# White background JPEG
result = client.remove(
    "photo.jpg",
    format="jpg",
    channels="rgb",
    bg_color="#ffffff"
)

# Small cropped thumbnail
result = client.remove(
    "photo.jpg",
    size="preview",
    crop=True
)

# Grayscale alpha mask only
result = client.remove("photo.jpg", channels="alpha")

# WebP for web
result = client.remove(
    "photo.jpg",
    format="webp",
    size="medium"
)

import asyncio
from poofbg import AsyncPoof

async def main():
    async with AsyncPoof() as client:
        result = await client.remove("photo.jpg")
        result.save("result.png")

asyncio.run(main())

import asyncio
from poofbg import AsyncPoof

async def process_images(image_paths: list[str]):
    async with AsyncPoof() as client:
        tasks = [client.remove(path) for path in image_paths]
        results = await asyncio.gather(*tasks)
        
        for path, result in zip(image_paths, results):
            output_path = path.replace(".jpg", "_no_bg.png")
            result.save(output_path)

asyncio.run(process_images(["photo1.jpg", "photo2.jpg", "photo3.jpg"]))

result = client.remove("photo.jpg")

# Raw image bytes
image_bytes: bytes = result.data

# Save to file
result.save("output.png")

# Metadata from response headers
print(f"Processing time: {result.processing_time_ms}ms")
print(f"Dimensions: {result.width}x{result.height}")
print(f"Request ID: {result.request_id}")

account = client.get_account()

print(f"Plan: {account.plan}")
print(f"Credits used: {account.used_credits}/{account.max_credits}")
print(f"Remaining: {account.max_credits - account.used_credits}")

from poofbg import Poof
from poofbg.exceptions import (
    PoofError,
    AuthenticationError,
    PaymentRequiredError,
    RateLimitError,
    ValidationError,
)

client = Poof()

try:
    result = client.remove("photo.jpg")
except AuthenticationError:
    print("Check your API key")
except PaymentRequiredError:
    print("Out of credits — upgrade your plan")
except RateLimitError as e:
    print(f"Rate limited. Retry after backoff. Request ID: {e.request_id}")
except ValidationError as e:
    print(f"Invalid request: {e.message}")
except PoofError as e:
    print(f"API error: {e.message} (Request ID: {e.request_id})")

import time
from poof.exceptions import RateLimitError

def remove_with_retry(client, image, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.remove(image)
        except RateLimitError:
            if attempt == max_retries - 1:
                raise
            wait = 2 ** attempt
            time.sleep(wait)

client = Poof(
    api_key="poof_your_api_key",
    base_url="https://api.poof.bg/v1",  # Default
    timeout=30.0,  # Request timeout in seconds
)

from poofbg import Poof, Result
from poofbg.types import Format, Size, Channels

def process_image(
    client: Poof,
    path: str,
    format: Format = "png",
    size: Size = "full",
) -> Result:
    return client.remove(path, format=format, size=size)