# Python ImageKit SDK

Quick start guide for ImageKit Python SDK - upload files, generate URLs, and integrate ImageKit into your Python applications.

---

The [ImageKit Python SDK](https://github.com/imagekit-developer/imagekit-python) provides a complete Python library for integrating ImageKit into your applications. Built with modern Python standards and full type safety via Pydantic models.

## What the SDK Does
- **URL generation** with image/video transformations
- **File uploads** to ImageKit's media library
- **File management** - list, search, update, delete files
- **Signed URLs** for private content delivery
- **Client-side upload authentication** tokens
- **Webhook verification** for event handling
- **Full type safety** with Pydantic models
- **Sync & async** support with httpx (Python 3.9+)

## Installation
```bash
pip install imagekitio
```

For better async performance with high concurrency:
```bash
pip install imagekitio[aiohttp]
```

## Quick Start
Get your API credentials from the [ImageKit Dashboard](/content/dashboard/developer/api-keys/index.html):
```python
import os
from imagekitio import ImageKit

imagekit = ImageKit(
    private_key=os.environ.get("IMAGEKIT_PRIVATE_KEY")
)

# Store URL endpoint for reuse
URL_ENDPOINT = os.environ.get("IMAGEKIT_URL_ENDPOINT")
```

## Common Examples
### Upload a File
```python
from pathlib import Path

# Upload from file
response = imagekit.files.upload(
    file=Path("product.jpg"),
    file_name="product.jpg",
    folder="/products",
    tags=["product", "featured"]
)
print(f"File ID: {response.file_id}")
print(f"URL: {response.url}")

# Upload from bytes (web forms)
image_data = request.files['image'].read()
response = imagekit.files.upload(
    file=image_data,
    file_name="upload.jpg"
)

# Stream large files
with open("video.mp4", "rb") as f:
    response = imagekit.files.upload(file=f, file_name="video.mp4")
```

### Generate Image URLs
For more examples of all transformation types, see the [URL generation guide](https://github.com/imagekit-developer/imagekit-python?tab=readme-ov-file#url-generation) on GitHub.
```python
# Basic transformation
url = imagekit.helper.build_url(
    url_endpoint=URL_ENDPOINT,
    src="/product.jpg",
    transformation=[{"width": 800, "height": 600, "format": "webp"}]
)
```

### Signed URLs
```python
# Expires in 1 hour
url = imagekit.helper.build_url(
    url_endpoint=URL_ENDPOINT,
    src="/private/doc.pdf",
    signed=True,
    expires_in=3600
)
```

### Image Overlays
```python
# Add watermark
url = imagekit.helper.build_url(
    url_endpoint=URL_ENDPOINT,
    src="/photo.jpg",
    transformation=[{\
        "overlay": {\
            "type": "image",\
            "input": "/logo.png",\
            "position": {"focus": "bottom_right"},\
            "transformation": [{"width": 100, "opacity": 70}]\
        }\
    }]
)

# Text overlay
url = imagekit.helper.build_url(
    url_endpoint=URL_ENDPOINT,
    src="/product.jpg",
    transformation=[{\
        "overlay": {\
            "type": "text",\
            "text": "SALE",\
            "position": {"focus": "top_left"},\
            "transformation": [{\
                "font_size": 48,\
                "font_color": "FF0000"\
            }]\
        }\
    }]
)
```

### Client-Side Upload Auth
For browser-based uploads, generate auth tokens:
```python
@app.route('/api/imagekit-auth')
def get_auth():
    return jsonify(imagekit.helper.get_authentication_parameters())
```

### Webhook Verification
```python
@app.route('/webhooks/imagekit', methods=['POST'])
def handle_webhook():
    try:
        event = imagekit.webhooks.unwrap(
            payload=request.get_data(as_text=True),
            headers=dict(request.headers),
            key=os.environ.get("IMAGEKIT_WEBHOOK_SECRET")
        )
        print(f"Event: {event.type}")
        return {"status": "success"}
    except Exception:
        return {"error": "Invalid signature"}, 401
```

### Complete API Reference
Every endpoint in the [ImageKit REST API Reference](/content/docs/api-reference/index.html) includes Python code snippets. To find all available methods and types in the SDK, refer to the [api.md](https://github.com/imagekit-developer/imagekit-python/blob/master/api.md) file.

### Learn More
- **[Image Transformations](/content/docs/image-transformation/index.html)** - All transformation parameters
- **[Video Transformations](/content/docs/video-transformation/index.html)** - Video-specific transformations
- **[Overlays](/content/docs/add-overlays-on-images/index.html)** - Advanced overlay options
- **[Webhooks](/content/docs/webhooks/index.html)** - Event types and webhook setup

### Support
- **Issues:** [GitHub Issues](https://github.com/imagekit-developer/imagekit-python/issues)
- **Email:** [support@imagekit.io](mailto:support@imagekit.io)