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()

Parameter	Type	Default	Description
image	str/Path/file	—	Image file (required)
format	str	"png"	png, webp, jpg, zip
size	str	"auto"	preview, medium, hd, full, auto
bg_color	str	None	Hex color, e.g. "#FFFFFF"
bg_image	str/Path/file	None	Background image file
crop	bool	False	Crop to object bounds
crop_margin	str	None	Margin, e.g. "10%"
scale	str	None	Object scale, e.g. "75%"
position	str	None	Position, e.g. "center"

remove_background_video()

Parameter	Type	Default	Description
video	str/Path/file	—	Video file (required)
format	str	"mp4"	mp4 or pro_bundle
processing_type	str	"human"	human or object
background_color	str	"#00B140"	Hex color
start_time_sec	float	0.0	Trim start (seconds)
end_time_sec	float	0.0	Trim end (0 = full)

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