Metadata-Version: 2.4
Name: bulkpicconv
Version: 1.0.0
Summary: Official Python SDK for the BulkPicConv image conversion API
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# bulkpicconv Python SDK

Official Python SDK for the BulkPicConv image conversion API.

## Requirements

- Python 3.9+
- No runtime dependencies outside the standard library

## Quick start

```python
from bulkpicconv import BulkPicConv

client = BulkPicConv("sk_your_api_key")
result = client.convert_file("photo.jpg", "photo.webp", {
    "format": "webp",
    "quality": 80,
})
print(result["saved_percent"])
```

## Methods

- `convert(image, options)`
- `resize(image, options)`
- `crop(image, options)`
- `optimize(image, options)`
- `watermark(image, watermark, options)`
- `create_batch(archive, options)`
- `get_batch_status(job_id)`
- `download_batch_result(job_id)`
- `convert_file(input_path, output_path, options)`
- `ai_alt_text(images, options)` — Generate descriptive alt text using AI
- `ai_rename(images, options)` — AI-suggest renamed filenames
- `ai_smart_crop(image, options)` — AI smart crop for platforms
- `ai_enhance(image, options)` — AI enhance image quality
- `ai_recommend(images, options)` — AI recommend optimal format
- `background_remove(image, options)` — Remove image background

Images accept a filesystem path or `bytes`. Image methods return a dictionary containing `buffer`, `input_size`, `output_size`, `saved_percent`, and `headers`.

## AI Methods

```python
# Generate alt text
result = client.ai_alt_text(["photo.jpg"], {"language": "en"})
# → {"alt_text": "...", "keywords": [...], "confidence": 0.95}

# Remove background
result = client.background_remove("product.jpg")
# result["buffer"] contains the transparent PNG
```

## BYOK (Bring Your Own Key)

Use your own OpenAI-compatible API key for AI methods:

```python
result = client.ai_alt_text(["image.jpg"], {
    "user_provider": {
        "base_url": "https://api.openai.com/v1",
        "model": "gpt-4o",
        "api_key": "sk-your-openai-key",
    },
})
```

## Configuration

```python
client = BulkPicConv(
    "sk_your_api_key",
    base_url="http://localhost:3000",
    timeout=30,
    max_retries=2,
)
```

The client retries network failures and HTTP 408, 429, 500, 502, 503, and 504. Other HTTP 4xx errors are raised immediately as `BulkPicConvError`.

## Local tests

```bash
python -m unittest discover -s tests
python -m compileall bulkpicconv
```
