openavaban

Python SDK for the openavaban REST API — manage profile avatars and banners via UploadThing and MongoDB.

Installation

pip install openavaban

Quick Start

1. Set up credentials

OPENAVABAN_API_URL=https://your-api.vercel.app
OPENAVABAN_API_KEY=your-api-key

2. Initialize the client

from openavaban import OpenavaBan

# Option 1: Auto-load from .env
client = OpenavaBan()

# Option 2: Pass directly
client = OpenavaBan(
    api_url="https://your-api.vercel.app",
    api_key="your-api-key"
)

Usage

Upload an avatar

avatar = client.upload(
    file="photo.jpg",
    name="Profile Photo",
    class_type="avatar",       # "avatar" or "banner"
    user_id="user_123",
    category="profile",
    tags=["main", "profile"]
)

print(avatar["url"])  # CDN URL

Get user's avatar

avatar = client.get(user_id="user_123", class_type="avatar")

Get all user's images

images = client.get_all(user_id="user_123")

Get image by ID

image = client.get_by_id("64f1a2b3...")

Update an image

client.update(
    image_id="64f1a2b3...",
    name="New Name",
    tags=["updated", "v2"]
)

Delete an image

client.delete("64f1a2b3...")

Query images

results = client.query(
    user_id="user_123",
    class_type="avatar",
    category="profile",
    tags=["main"]
)

Response Format

{
    "id": "64f1a2b3...",
    "name": "Profile Photo",
    "class_type": "avatar",
    "category": "profile",
    "url": "https://your-app-id.ufs.sh/f/...",
    "user_id": "user_123",
    "created_at": "2026-08-09T10:00:00+00:00",
    "updated_at": "2026-08-09T10:00:00+00:00",
    "file_size": 102400,
    "mime_type": "image/jpeg",
    "tags": ["main", "profile"],
    "metadata": {},
    "dimensions": {"width": 800, "height": 600}
}

Exceptions

Environment Variables

License

MIT