claidai 1.1.0

Python client and CLI for the Claid.ai image editing API

claidai

Python client and CLI for the Claid.ai image editing API.

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

---

Installation

pip install claidai

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

export CLAID_API_KEY="your_api_key_here"

Get your API key at claid.ai/account/api.

---

Python API — Single File

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

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

# 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

# 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

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