Python ImageKit SDK

The ImageKit Python SDK 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

Copy

pip install imagekitio

For better async performance with high concurrency:

Copy

pip install imagekitio[aiohttp]

Quick Start

Get your API credentials from the ImageKit Dashboard:

Copy

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

Copy

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 on GitHub.

Copy

# Basic transformation
url = imagekit.helper.build_url(
    url_endpoint=URL_ENDPOINT,
    src="/product.jpg",
    transformation=[{
        "width": 800,
        "height": 600,
        "format": "webp"
    }]
)

Signed URLs

Copy

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

Image Overlays

Copy

# 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:

Copy

@app.route('/api/imagekit-auth')
def get_auth():
    return jsonify(imagekit.helper.get_authentication_parameters())

Webhook Verification

Copy

@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 includes Python code snippets. To find all available methods and types in the SDK, refer to the api.md file.

Learn More

Image Transformations - All transformation parameters
Video Transformations - Video-specific transformations
Overlays - Advanced overlay options
Webhooks - Event types and webhook setup

Support

Issues: GitHub Issues
Email: support@imagekit.io