Metadata-Version: 2.4
Name: claidai
Version: 1.1.0
Summary: Python client and CLI for the Claid.ai image editing API
Author: Kumaresan
License: MIT
Keywords: claid,image,ai,background-removal,upscale
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Requires-Dist: click>=8.1

# claidai

Python client and CLI for the [Claid.ai](https://claid.ai) image editing API.

AI-powered background removal, upscaling, blur, colour enhancement, smart crop, outpaint, batch folder processing and more.

---

## Installation

```bash
pip install claidai
```

Set your API key as an environment variable (recommended):

```bash
export CLAID_API_KEY="your_api_key_here"
```

Get your API key at [claid.ai/account/api](https://claid.ai/account/api).


---

## Python API — Single File

```python
from claidai import Claid

c = Claid("YOUR_API_KEY")

# Remove background → transparent PNG
c.remove_bg("photo.jpg").save("photo_nobg.png")

# Remove background → white background
c.remove_bg("photo.jpg", bg_color="#ffffff").save("photo_white.jpg")

# Remove background → custom colour
c.remove_bg("photo.jpg", bg_color="#f0f0f0", category="products").save("photo_grey.jpg")

# AI Upscale 2×
c.upscale("photo.jpg", scale="200%", method="smart_enhance").save("photo_2x.jpg")

# AI Upscale 4× for portraits
c.upscale("portrait.jpg", scale="400%", method="faces").save("portrait_4x.jpg")

# AI Upscale for illustrations
c.upscale("art.jpg", scale="200%", method="digital_art").save("art_2x.jpg")

# Blur background (lens blur, high strength)
c.blur_bg("photo.jpg", blur_type="lens", level="high").save("photo_blur.jpg")

# Blur background (Gaussian, medium)
c.blur_bg("photo.jpg", blur_type="regular", level="medium").save("photo_blur2.jpg")

# Colour enhancement with HDR
c.enhance("photo.jpg", hdr=80, sharpness=40).save("photo_enhanced.jpg")

# Manual colour adjustments
c.enhance("photo.jpg", exposure=20, saturation=30, contrast=15).save("photo_adj.jpg")

# Smart crop to 800×800 square
c.resize("photo.jpg", width=800, height=800, smart=True).save("photo_sq.jpg")

# Resize keeping aspect ratio
c.resize("photo.jpg", width=1200, fit="bounds").save("photo_1200.jpg")

# Sharpen + remove JPEG artefacts
c.polish("photo.jpg").save("photo_polished.jpg")

# Expand canvas with AI background
c.outpaint("photo.jpg", width="150%").save("photo_wide.jpg")

# Convert to WebP
c.convert("photo.jpg", output_format="webp").save("photo.webp")

# Convert to PNG with max quality
c.convert("photo.jpg", output_format="png", quality=100).save("photo.png")
```

---

## Python API — Entire Folder

```python
from claidai import Claid, process_folder

c = Claid("YOUR_API_KEY")

# Remove background from ALL images in a folder
result = process_folder(
    c,
    input_folder  = "photos/",
    output_folder = "photos_nobg/",
    operation     = c.remove_bg,
    output_format = "png",
    workers       = 3,
)
print(result)
# BatchResult: 24/25 succeeded, 1 failed

# Upscale entire folder
result = process_folder(
    c,
    input_folder     = "raw/",
    output_folder    = "upscaled/",
    operation        = c.upscale,
    operation_kwargs = {"scale": "200%", "method": "smart_enhance"},
    output_format    = "jpeg",
    workers          = 3,
)

# Enhance entire folder (operation_kwargs required for enhance)
result = process_folder(
    c,
    input_folder     = "photos/",
    output_folder    = "photos_enhanced/",
    operation        = c.enhance,
    operation_kwargs = {"hdr": 80, "sharpness": 40},
    output_format    = "jpeg",
    workers          = 3,
)

# Process sub-folders recursively, skip already-done files
result = process_folder(
    c,
    input_folder     = "input/",
    output_folder    = "output/",
    operation        = c.enhance,
    operation_kwargs = {"hdr": 80, "sharpness": 40},
    recursive        = True,
    skip_existing    = True,
    workers          = 4,
)

# Check results
print(f"Succeeded : {result.success_count}")
print(f"Failed    : {result.fail_count}")
for filepath, error in result.failed:
    print(f"  {filepath.name}: {error}")
```

---

## operation_kwargs Reference

> ⚠️ `enhance` **always** requires `operation_kwargs` — it will fail without at least one value.

| Operation | Required `operation_kwargs` | Example |
|-----------|----------------------------|---------|
| `remove_bg` | None (optional) | `{"category": "products", "bg_color": "transparent"}` |
| `upscale` | None (optional) | `{"scale": "200%", "method": "smart_enhance"}` |
| `blur_bg` | None (optional) | `{"blur_type": "lens", "level": "high"}` |
| `enhance` | ✅ **Required** | `{"hdr": 80, "sharpness": 40}` |
| `polish` | None (optional) | `{"decompress": "auto"}` |
| `resize` | ✅ **Required** (`width`) | `{"width": 800, "height": 800, "smart": True}` |
| `outpaint` | None (optional) | `{"width": "150%", "feathering": "20%"}` |
| `convert` | None | `{}` |

---

## CLI — Single File

```bash
# Set key once
export CLAID_API_KEY="your_key_here"

# Remove background
claidai remove-bg photo.jpg -o out.png
claidai remove-bg photo.jpg --bg-color "#ffffff" --format jpeg -o out.jpg
claidai remove-bg photo.jpg --category cars -o car_nobg.png
claidai remove-bg photo.jpg --no-clipping -o out.png

# AI Upscale
claidai upscale photo.jpg -o out.jpg --scale 200% --method smart_enhance
claidai upscale portrait.jpg --scale 400% --method faces -o portrait_4x.jpg
claidai upscale art.jpg --scale 200% --method digital_art -o art_2x.jpg

# Blur background
claidai blur-bg photo.jpg -o out.jpg --type lens --level high
claidai blur-bg photo.jpg --type regular --level medium --category products

# Colour enhancement
claidai enhance photo.jpg -o out.jpg --hdr 80 --sharpness 40
claidai enhance photo.jpg --exposure 20 --saturation 30 --contrast 15

# Resize
claidai resize photo.jpg -o out.jpg --width 800 --height 800 --smart
claidai resize photo.jpg --width 1200 --fit bounds
claidai resize photo.jpg --width 150% --fit outpaint

# Polish (sharpen + denoise)
claidai polish photo.jpg -o out.jpg
claidai polish photo.jpg --decompress strong -o out.jpg

# Outpaint (expand canvas)
claidai outpaint photo.jpg -o out.jpg --width 150% --feathering 20%
claidai outpaint photo.jpg --width 200% --height 150%

# Convert format
claidai convert photo.jpg --format webp -o photo.webp
claidai convert photo.jpg --format png --quality 100
```

---

## CLI — Batch Folder

```bash
# Remove background from all images in a folder
claidai batch photos/ photos_nobg/ --operation remove-bg --format png

# Upscale entire folder with 3 parallel workers
claidai batch raw/ upscaled/ --operation upscale --scale 200% --workers 3

# Enhance all images (--hdr or --sharpness required)
claidai batch input/ output/ --operation enhance --hdr 80 --sharpness 40

# Enhance all images recursively (including sub-folders)
claidai batch input/ output/ --operation enhance --hdr 80 --sharpness 40 --recursive

# Skip already processed files (safe to re-run)
claidai batch input/ output/ --operation polish --skip-existing

# Blur backgrounds for all product images
claidai batch products/ products_blur/ --operation blur-bg --type lens --level high

# Convert all images to WebP
claidai batch input/ output/ --operation convert --format webp
```

---

## Available Operations

| Method | CLI Command | Description |
|--------|-------------|-------------|
| `remove_bg()` | `remove-bg` | AI background removal |
| `upscale()` | `upscale` | AI image upscaling (2×–4×) |
| `blur_bg()` | `blur-bg` | Background blur (Gaussian / lens) |
| `enhance()` | `enhance` | HDR, exposure, saturation, contrast, sharpness |
| `resize()` | `resize` | Resize with smart crop, bounds, cover, canvas |
| `polish()` | `polish` | Sharpen details + remove JPEG artefacts |
| `outpaint()` | `outpaint` | AI canvas expansion |
| `convert()` | `convert` | Format conversion (JPEG / PNG / WebP / AVIF / TIFF) |
| `process_folder()` | `batch` | Batch process entire folders |

---

## Upscale Methods

| Method | Best For |
|--------|----------|
| `smart_enhance` | Products, food, real estate (default) |
| `smart_resize` | High-quality photos with text |
| `photo` | Nature, architecture, phone photos |
| `faces` | Portraits and people |
| `digital_art` | Illustrations, anime, drawings |

---

## Error Handling

```python
from claidai import Claid
from claidai.exceptions import (
    ClaidAuthError,
    ClaidNoCreditsError,
    ClaidRateLimitError,
    ClaidValidationError,
    ClaidFileError,
)

c = Claid("YOUR_API_KEY")

try:
    c.remove_bg("photo.jpg").save("out.png")
except ClaidAuthError:
    print("Invalid API key")
except ClaidNoCreditsError:
    print("Out of credits — top up at claid.ai")
except ClaidRateLimitError:
    print("Rate limit hit — slow down requests")
except ClaidValidationError as e:
    print(f"Bad request: {e}")
except ClaidFileError as e:
    print(f"File error: {e}")
```

---

## Supported Formats

| Type | Formats |
|------|---------|
| Input | JPEG, PNG, WebP, AVIF, HEIC, BMP, TIFF, GIF |
| Output | JPEG, PNG, WebP, AVIF, TIFF |

---

## License

MIT

