Skip to main content

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.

PyPI Python License CI

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

License

MIT

Metadata

Release files for carvesdk 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for carvesdk 1.0.0
File Size Uploaded Provenance Actions
carvesdk-1.0.0.tar.gz 10.7 kB With provenance Details for carvesdk-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for carvesdk 1.0.0
File Interpreter ABI Platform Actions
carvesdk-1.0.0-py3-none-any.whl Python 3 none any Details for carvesdk-1.0.0-py3-none-any.whl

Total release size: 17.7 kB

Release files / carvesdk-1.0.0.tar.gz

Download URL carvesdk-1.0.0.tar.gz
Size 10.7 kB
Tags Source
SHA-256 checksum
How to use checksums
c9e9a57628f210cf64ff7e8397a0f7281ef59446923b865139650528b1d65698
BLAKE2b-256 checksum
How to use checksums
21b7a6429e19dbae69357f08d60959c111c587c8b0ef336e68936e605d0c7db1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 6, 2026.

Transparency log

Release files / carvesdk-1.0.0-py3-none-any.whl

Download URL carvesdk-1.0.0-py3-none-any.whl
Size 7.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d1857c954dee7e1eee13802b5beeef141e83e584b9b0bfde77096dae4080f05f
BLAKE2b-256 checksum
How to use checksums
911de49080a42e875761b29929e267c4f6450bf1a7bbf9d38d1ae1fef4e8b7fc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 6, 2026.

Transparency log

Security for carvesdk 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for carvesdk-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page