Metadata-Version: 2.4
Name: imghippo
Version: 1.0.1
Summary: Official Python SDK for the Imghippo API — upload, compress, convert, remove backgrounds, resize, crop, rotate/flip, JPG↔PDF, and OCR.
Author-email: Imghippo <info@imghippo.com>
License: MIT
Project-URL: Homepage, https://www.imghippo.com/docs/python-sdk
Project-URL: Repository, https://github.com/imghippo/imghippo-python
Project-URL: Documentation, https://www.imghippo.com/docs/python-sdk
Project-URL: Bug Tracker, https://www.imghippo.com/help/contact-support
Keywords: imghippo,image,upload,compress,convert,remove-background,resize,crop,ocr,jpg-to-pdf,pdf-to-jpg,rotate,flip,api,sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typing_extensions>=4.0
Dynamic: license-file

# imghippo

Official Python SDK for the [Imghippo API](https://www.imghippo.com/docs/rest-api) — upload, compress, convert, remove backgrounds, resize, crop, rotate/flip, JPG↔PDF, and OCR.

[![PyPI version](https://img.shields.io/pypi/v/imghippo)](https://pypi.org/project/imghippo/)
[![Python versions](https://img.shields.io/pypi/pyversions/imghippo)](https://pypi.org/project/imghippo/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## Installation

```bash
pip install imghippo
```

Requires Python 3.8+. No third-party HTTP dependencies — uses the standard library only.

Get your API key at [www.imghippo.com/settings](https://www.imghippo.com/settings?tab=api).

---

## Quick Start

```python
from imghippo import Imghippo

client = Imghippo("your_api_key")

# Upload an image
result = client.upload.upload("photo.jpg")
print(result["data"]["url"])

# Compress a batch of images
result = client.compress.compress(["a.jpg", "b.jpg"])
for item in result["data"]:
    print(item["output_url"], item["saved_percent"])

# Remove background
result = client.remove_bg.remove("portrait.jpg")
print(result["data"][0]["output_url"])
```

---

## File Input

Every method accepts files in any of these forms:

```python
# Local file path (str or Path)
client.compress.compress("photo.jpg")
client.compress.compress(Path("photo.jpg"))

# Bytes tuple — (data, filename)
with open("photo.jpg", "rb") as f:
    client.compress.compress((f.read(), "photo.jpg"))

# Bytes tuple with MIME type — (data, filename, mime_type)
client.compress.compress((data, "photo.jpg", "image/jpeg"))

# File-like object
with open("photo.jpg", "rb") as f:
    client.compress.compress(f)

# List of any of the above (batch)
client.compress.compress(["a.jpg", "b.jpg", "c.jpg"])
```

---

## API Reference

### `upload`

#### `upload.upload(file, params?)`

Upload a single image.

```python
from imghippo import Imghippo, UploadParams

client = Imghippo("your_api_key")

result = client.upload.upload("photo.jpg", UploadParams(title="My Photo"))
print(result["data"]["url"])        # https://i.imghippo.com/files/abc.jpg
print(result["data"]["view_url"])   # same URL
print(result["data"]["size"])       # file size in bytes
```

| Param | Type | Description |
|---|---|---|
| `file` | `FileInput` | File path, bytes tuple, or file-like object |
| `params.title` | `str \| None` | Optional title for the image |

---

#### `upload.delete(params)`

Delete an image by its URL.

```python
from imghippo import DeleteParams

client.upload.delete(DeleteParams(url="https://i.imghippo.com/files/abc.jpg"))
```

| Param | Type | Description |
|---|---|---|
| `params.url` | `str` | Full URL of the image to delete |

---

### `compress`

All compress methods accept up to 5 files per request and return a `CompressBatchResponse`.

#### `compress.compress(files, params?)`

Compress one or more images — auto-detects format (JPG, PNG, GIF, SVG).

```python
from imghippo import CompressParams

result = client.compress.compress(["a.jpg", "b.png"], CompressParams(quality="high"))
for item in result["data"]:
    if item["status"] == "success":
        print(item["output_url"], f'{item["saved_percent"]}% saved')
```

#### `compress.jpg(files, params?)` · `compress.png(files, params?)` · `compress.gif(files, params?)` · `compress.svg(files, params?)`

Format-specific compression methods — same signature as `compress.compress()`.

| Param | Type | Description |
|---|---|---|
| `files` | `FileInput \| list[FileInput]` | One or more files |
| `params.quality` | `"low" \| "medium" \| "high"` | Compression quality (default: `"medium"`) |

---

### `convert`

All convert methods accept up to 5 files per request and return a `ConvertBatchResponse`.

```python
result = client.convert.jpg_to_png(["a.jpg", "b.jpg"])
for item in result["data"]:
    if item["status"] == "success":
        print(item["output_url"])
```

| Method | Input format | Output format |
|---|---|---|
| `convert.png_to_jpg(files)` | PNG | JPG |
| `convert.jpg_to_png(files)` | JPG | PNG |
| `convert.jpg_to_webp(files)` | JPG | WebP |
| `convert.webp_to_jpg(files)` | WebP | JPG |
| `convert.heic_to_jpg(files)` | HEIC | JPG |
| `convert.word_to_pdf(files)` | DOCX / DOC | PDF |

---

### `remove_bg`

#### `remove_bg.remove(files)`

Remove the background from one or more images. Accepts up to 5 files per request.

```python
result = client.remove_bg.remove("portrait.jpg")
print(result["data"][0]["output_url"])
```

| Param | Type | Description |
|---|---|---|
| `files` | `FileInput \| list[FileInput]` | One or more images |

---

### `resize`

#### `resize.resize(files, params)`

Resize one or more images. At least one of `width` or `height` is required. Aspect ratio is preserved.

```python
from imghippo import ResizeParams

result = client.resize.resize("photo.jpg", ResizeParams(width=800))
print(result["data"][0]["output_url"])
```

| Param | Type | Description |
|---|---|---|
| `files` | `FileInput \| list[FileInput]` | One or more images |
| `params.width` | `int \| None` | Target width in pixels |
| `params.height` | `int \| None` | Target height in pixels |

---

### `crop`

#### `crop.crop(file, params)`

Crop a single image. Coordinates are in pixels from the top-left corner.

```python
from imghippo import CropParams

result = client.crop.crop("photo.jpg", CropParams(x=100, y=50, width=400, height=300))
print(result["data"][0]["output_url"])
```

| Param | Type | Description |
|---|---|---|
| `file` | `FileInput` | A single image |
| `params.x` | `int` | X offset from left edge in pixels |
| `params.y` | `int` | Y offset from top edge in pixels |
| `params.width` | `int` | Width of the crop region in pixels |
| `params.height` | `int` | Height of the crop region in pixels |

---

### `ocr`

#### `ocr.extract(file)`

Extract text from an image or document. Supports JPG, PNG, WebP, PDF, TIFF.

```python
result = client.ocr.extract("document.jpg")
print(result["data"]["text"])
print(result["data"]["page_count"])
```

| Param | Type | Description |
|---|---|---|
| `file` | `FileInput` | A single image or document |

---

### `jpg_to_pdf`

#### `jpg_to_pdf.convert(files)`

Convert one or more JPG images into a single PDF. Accepts up to 5 files per request.

```python
result = client.jpg_to_pdf.convert(["page1.jpg", "page2.jpg"])
print(result["data"]["url"])   # URL of the generated PDF
print(result["data"]["size"])  # file size in bytes
```

| Param | Type | Description |
|---|---|---|
| `files` | `FileInput \| list[FileInput]` | One or more JPG images (up to 5) |

---

### `pdf_to_jpg`

#### `pdf_to_jpg.convert(file)`

Convert a PDF to JPG images.

```python
result = client.pdf_to_jpg.convert("document.pdf")
print(result["data"]["url"])   # URL of the output
print(result["data"]["size"])  # file size in bytes
```

| Param | Type | Description |
|---|---|---|
| `file` | `FileInput` | A single PDF file |

---

### `rotate_flip`

#### `rotate_flip.transform(files, params?)`

Rotate and/or flip one or more images.

```python
from imghippo import RotateFlipParams

result = client.rotate_flip.transform("photo.jpg", RotateFlipParams(angle=90, flip="horizontal"))
for item in result["data"]:
    if item["status"] == "success":
        print(item["output_url"])
```

| Param | Type | Description |
|---|---|---|
| `files` | `FileInput \| list[FileInput]` | One or more images |
| `params.angle` | `0 \| 90 \| 180 \| 270` | Rotation angle in degrees (default: `0`) |
| `params.flip` | `"none" \| "horizontal" \| "vertical" \| "both"` | Flip direction (default: `"none"`) |

---

## Error Handling

All API errors raise `ImghippoError`.

```python
from imghippo import Imghippo, ImghippoError

client = Imghippo("your_api_key")

try:
    result = client.upload.upload("photo.jpg")
except ImghippoError as e:
    print(e.message)      # human-readable error message
    print(e.status_code)  # HTTP status code (0 for network/timeout errors)
    print(e.raw)          # full parsed response body
```

### Common status codes

| Status | Meaning |
|---|---|
| `400` | Bad request — missing or invalid parameters |
| `401` | Invalid or missing API key |
| `402` | Insufficient credits |
| `403` | Account suspended or blocked |
| `413` | File too large |
| `429` | Rate limit exceeded |
| `500` | Internal server error |

---

## Configuration

Pass an `ImghippoConfig` for advanced options:

```python
from imghippo import Imghippo, ImghippoConfig

client = Imghippo(ImghippoConfig(
    api_key="your_api_key",
    timeout=120,           # seconds (default: 60)
    base_url="https://api.imghippo.com",  # override for testing
))
```

---

## License

MIT © [Imghippo](https://www.imghippo.com)
