carvesdk

Remove backgrounds from images and videos with the Carve.Photos API. Python SDK that handles uploads, polling, and downloads — pass a file, get the result.

Installation

pip install carvesdk

Quick Start

Remove background from image

from carvesdk import CarveClient

client = CarveClient("YOUR_API_KEY")

# Simple usage
result = client.remove_background("photo.jpg")
result.save("result.png")

# With parameters
result = client.remove_background(
    "photo.jpg",
    format="webp",
    size="hd",
    bg_color="#FFFFFF",
    crop=True,
    crop_margin="5%",
)
result.save("result.webp")

Remove background from video

from carvesdk import CarveClient

client = CarveClient("YOUR_API_KEY")

# Simple usage
result = client.remove_background_video("video.mp4")
result.save("result.mp4")

# With parameters
result = client.remove_background_video(
    "video.mp4",
    format="mp4",
    processing_type="human",
    background_color="#00B140",
    start_time_sec=2.0,
    end_time_sec=8.5,
)
result.save("result.mp4")

# Pro bundle (ZIP with alpha channel)
result = client.remove_background_video("video.mp4", format="pro_bundle")
result.save("result.zip")

Check balance

balance = client.get_balance()
print(f"Balance: {balance['total']} credits")

API Key

Get your API key at carve.photos/profile.
Free credits are included with registration.

Features

• Images: PNG, JPEG, WebP, AVIF — up to 25 megapixels
• Video: MP4, MOV, WEBM — up to 4K, 30 seconds
• Output formats: PNG, WebP, JPG, ZIP (images) / MP4, pro_bundle (video)
• Customization: crop, scale, position, ROI, background color/image
• Automatic polling: SDK handles status polling internally

Parameters

remove_background()

remove_background_video()

Error Handling

from carvesdk import CarveClient
from carvesdk.client import CarveError

client = CarveClient("YOUR_API_KEY")

try:
    result = client.remove_background("photo.jpg")
    result.save("result.png")
except CarveError as e:
    print(f"Error: {e}")
    print(f"Status code: {e.status_code}")
    print(f"Detail: {e.detail}")

Documentation

• API Documentation
• Swagger
• Pricing

License

MIT