Metadata-Version: 2.4
Name: carvesdk
Version: 0.1.0
Summary: Python SDK for Carve.Photos — background removal API for images and videos
Author-email: "Carve.Photos" <contact@carve.photos>
License: MIT
Project-URL: Homepage, https://carve.photos
Project-URL: Documentation, https://carve.photos/help/api-docs
Project-URL: Repository, https://github.com/Carve-Photos/sdk-python
Project-URL: Bug Tracker, https://github.com/Carve-Photos/sdk-python/issues
Keywords: background-removal,remove-background,image-processing,video-processing,carvesdk,api,sdk,background,foreground,segmentation,matting,chroma-key
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Dynamic: license-file

# carvesdk

Python SDK for [Carve.Photos](https://carve.photos) — background removal API for images and videos.

[![PyPI](https://img.shields.io/pypi/v/carvesdk)](https://pypi.org/project/carvesdk/)
[![Python](https://img.shields.io/pypi/pyversions/carvesdk)](https://pypi.org/project/carvesdk/)
[![License](https://img.shields.io/pypi/l/carvesdk)](https://github.com/Carve-Photos/sdk-python/blob/main/LICENSE)

## Installation

```bash
pip install carvesdk
```

## Quick Start

### Remove background from image

```python
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

```python
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

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

## API Key

Get your API key at [carve.photos/profile](https://carve.photos/profile?tab=api-key).  
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

```python
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](https://carve.photos/help/api-docs)
- [Swagger](https://api.carve.photos/api/docs)
- [Pricing](https://carve.photos/pricing)

## License

MIT
