# Deflato Python SDK

Compress images, documents, and generate AI images with one line of code. Powered by [deflato.com](https://deflato.com).

## Install

```bash
pip install deflato
```

## Quick Start

```python
from deflato import Deflato

client = Deflato("your-api-key")

# Compress an image
result = client.compress("photo.jpg", format="WEBP", quality=75)
print(f"Saved {result.savings_percent}% -> {result.output_path}")

# Compress a PDF document
doc = client.compress_document("report.pdf", quality=70)
print(f"PDF: {doc.savings_percent}% smaller")

# Generate an AI image
img = client.generate("A sunset over mountains", model="fast")
print(f"Generated -> {img.output_path}")

# Edit an image with AI
edited = client.edit("Add sunglasses to the person", input_path="portrait.jpg")
print(f"Edited -> {edited.output_path}")

# Get alt-text for an image
desc = client.describe(input_path="photo.jpg")
print(desc.description)
```

## API

### `Deflato(api_key, base_url="https://deflato.com")`

---

### `client.compress(input_path, output=None, quality=80, max_dimension=0, format="JPEG", strip_exif=True)`

Compress an image file.

Returns `CompressResult`:
- `success: bool`
- `input_size: int` (bytes)
- `output_size: int` (bytes)
- `savings_percent: int`
- `output_path: str`
- `output_format: str`

---

### `client.info(input_path, quality=80, format="JPEG")`

Get compression info without saving the file. Returns `CompressResult`.

---

### `client.compress_batch(input_paths, output_dir=None, quality=80, format="JPEG")`

Compress multiple files. Returns list of `CompressResult`.

---

### `client.compress_document(input_path, output=None, quality=75, max_dimension=1920)`

Compress images inside PDF, DOCX, PPTX, or XLSX documents. Returns `CompressResult`.

---

### `client.convert_format(input_path, output_format, output=None)`

Convert an image to a different format (JPEG, PNG, WEBP, AVIF). Returns `CompressResult`.

---

### `client.generate(prompt, output=None, model="photo", aspect_ratio="1:1", style="any", resolution="1K", format="png")`

Generate an image from a text prompt using AI.

| Param | Default | Description |
|---|---|---|
| model | photo | fast, photo, design, or icon |
| aspect_ratio | 1:1 | Aspect ratio |
| style | any | Style for design/icon models |
| resolution | 1K | 1K, 2K, or 4K (photo only) |
| format | png | png or jpg |

Returns `GenerateResult`: `success`, `output_path`, `output_size`, `model`, `prompt`

---

### `client.edit(prompt, input_path=None, image_url=None, output=None, model="fast", format="png")`

Edit an existing image using AI instructions (img2img).

| Param | Default | Description |
|---|---|---|
| input_path | — | Path to local image file |
| image_url | — | URL of the image (alternative) |
| model | fast | fast (~10s) or precise (~30s) |
| format | png | png or jpg |

Returns `EditResult`: `success`, `output_path`, `output_size`, `model`, `prompt`

---

### `client.describe(input_path=None, image_url=None)`

Generate AI alt-text / caption for an image. Free — no rate limit.

Returns `DescribeResult`: `success`, `description`

---

## Supported Formats

**Image input:** JPEG, PNG, WEBP, HEIC, TIFF, BMP, GIF, RAW (20+ formats)

**Image output:** JPEG, PNG, WEBP, AVIF

**Document input:** PDF, DOCX, PPTX, XLSX

## Get API Key

1. Sign up at [deflato.com](https://deflato.com)
2. Go to [Account](https://deflato.com/en/account) -> Generate API Key

## License

MIT
