Home Documentation Bulk Upload

About

REST API for managing profile avatars and banners with a public gallery.

openavaban-api is a simple, hosted image management API. Upload images, store metadata, and browse everything through a built-in gallery — no setup required.

Features

  • Image Upload — Upload avatars and banners with metadata, tags, and categories
  • Public Gallery — Giphy-style masonry grid with search and filters
  • Search — Full-text search across name, tags, category, and user ID
  • Random Image — Get random images, optionally filtered by category
  • Bulk Upload — Upload up to 100 images at once using a CSV file
  • CRUD Operations — Create, read, update, and delete images
  • REST API — Simple JSON endpoints for any client
  • Python Library — pip install openavaban

Base URL

https://openavaban-api.giripratik.com.np

Source Code

github.com/the-ripper77/openavaban-api

Quick Start

Make your first API call in 2 minutes.

Visit openavaban-api.giripratik.com.np to see all uploaded images in a searchable grid.

2. Search for Images

curl "https://openavaban-api.giripratik.com.np/api/search?q=cute"

3. Get a Random Image

curl "https://openavaban-api.giripratik.com.np/api/random"

4. Upload an Image

curl -X POST "https://openavaban-api.giripratik.com.np/api/upload" \
  -H "X-API-Key: your-api-key" \
  -F "file=@photo.jpg" \
  -F "name=Profile Photo" \
  -F "class_type=avatar" \
  -F "user_id=user_123"

5. Python Library

pip install openavaban

from openavaban import OpenavaBan

client = OpenavaBan()

# Get all avatars
images = client.get_all(user_id="user_123")

# Upload a new avatar
result = client.upload(
    file="photo.jpg",
    name="Profile Photo",
    class_type="avatar",
    user_id="user_123"
)

Next Steps

Python SDK

Install the openavaban Python package to interact with the API without writing raw HTTP requests.

Installation

pip install openavaban

Quick Start

from openavaban import OpenavaBan

client = OpenavaBan()  # uses hosted API

# Upload
result = client.upload("photo.jpg", name="Profile Photo", class_type="avatar")
print(result["url"])

# Search
results = client.search(class_type="avatar")
for img in results["results"]:
    print(img["name"], img["url"])

# Random
random_imgs = client.random(count=5)

No API keys or database credentials needed.

Methods

Upload Image

result = client.upload(
    file="photo.jpg",          # file path or file-like object
    name="Profile Photo",      # display name
    class_type="avatar",       # "avatar" or "banner"
    category="profile",        # optional category
    tags=["main", "profile"],  # optional tags list
    metadata={"source": "web"} # optional metadata dict
)

Returns:

{
    "id": "64f1a2b3...",
    "name": "Profile Photo",
    "class_type": "avatar",
    "category": "profile",
    "url": "https://utfs.io/f/...",
    "tags": ["main", "profile"],
    "created_at": "2026-08-09T10:00:00+00:00",
    ...
}

Bulk Upload

result = client.bulk_upload("images.csv")
print(f"Uploaded {result['success']}/{result['total']}")

CSV format:

file_url,name,class_type,category,tags
https://example.com/photo1.jpg,Profile Photo,avatar,profile,"main,profile"
https://example.com/banner1.png,Social Banner,banner,social,"banner,v2"

Search Images

results = client.search(
    q="profile",           # search across name, tags, category
    class_type="avatar",   # filter by type
    category="profile",    # filter by category
    tags=["main"],         # filter by tags (AND)
    mime_type="gif",       # "image" or "gif"
    limit=30,              # max 100
    offset=0               # pagination
)

Returns:

{
    "total": 42,
    "offset": 0,
    "limit": 30,
    "has_more": True,
    "results": [...]
}

Random Images

result = client.random(category="profile", count=5)
# Returns {"images": [...]}

Get by ID

image = client.get("image_id_here")

Update

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

Delete

client.delete("image_id_here")

Custom API URL

Point to a different API instance:

client = OpenavaBan(base_url="http://localhost:3000")

Exceptions

Exception Description
APIError API request failed
InvalidClassError Invalid class_type
NotFoundError Image not found
ValidationError Invalid file or missing fields 
from openavaban import OpenavaBan, NotFoundError

client = OpenavaBan()
try:
    image = client.get("nonexistent_id")
except NotFoundError:
    print("Image not found")

Search Images

Search for images across name, tags, category, and user ID. No API key required.

Endpoint

GET /api/search

Parameters

Parameter Type Required Default Description
q string No — Search query (searches name, tags, category, user_id)
class_type string No — Filter by avatar or banner
category string No — Filter by category (partial match)
tags string No — Comma-separated tags (AND logic)
limit integer No 30 Max results (1-100)
offset integer No 0 Skip N results for pagination

Response

{
  "total": 42,
  "offset": 0,
  "limit": 30,
  "has_more": true,
  "results": [
    {
      "id": "64f1a2b3...",
      "name": "Profile Photo",
      "class_type": "avatar",
      "category": "profile",
      "url": "https://utfs.io/f/...",
      "key": "...",
      "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 }
    }
  ]
}

Examples

Search by keyword

curl "https://openavaban-api.giripratik.com.np/api/search?q=cute"

Filter by type

curl "https://openavaban-api.giripratik.com.np/api/search?class_type=avatar"

Search with tags

curl "https://openavaban-api.giripratik.com.np/api/search?tags=main,profile"

Pagination

# Page 1
curl "https://openavaban-api.giripratik.com.np/api/search?limit=10&offset=0"

# Page 2
curl "https://openavaban-api.giripratik.com.np/api/search?limit=10&offset=10"

Combined filters

curl "https://openavaban-api.giripratik.com.np/api/search?q=anime&class_type=banner&limit=5"

JavaScript Example

const res = await fetch('/api/search?q=cute&limit=10');
const data = await res.json();

data.results.forEach(image => {
  console.log(image.name, image.url);
});

Python Example

import requests

res = requests.get(
    "https://openavaban-api.giripratik.com.np/api/search",
    params={"q": "cute", "limit": 10}
)
data = res.json()

for image in data["results"]:
    print(image["name"], image["url"])

Upload Image

Upload an image (avatar or banner) with metadata.

Endpoint

POST /api/upload

Headers

Header Required Description
Content-Type Yes multipart/form-data

Form Fields

Field Type Required Description
file file Yes Image file (jpg, png, gif, webp). Max 10 MB
name string Yes Display name for the image
class_type string Yes avatar or banner
user_id string No User identifier
category string No Category string (e.g., "profile", "social")
tags string No Comma-separated tags (e.g., "main,profile")
metadata string No JSON string of custom metadata

Response

{
  "id": "64f1a2b3...",
  "name": "Profile Photo",
  "class_type": "avatar",
  "category": "profile",
  "url": "https://utfs.io/f/...",
  "key": "...",
  "user_id": "",
  "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 }
}

Examples

curl

curl -X POST "https://openavaban-api.giripratik.com.np/api/upload" \
  -F "file=@photo.jpg" \
  -F "name=Profile Photo" \
  -F "class_type=avatar" \
  -F "category=profile" \
  -F "tags=main,profile"

Python

import requests

res = requests.post(
    "https://openavaban-api.giripratik.com.np/api/upload",
    files={"file": open("photo.jpg", "rb")},
    data={
        "name": "Profile Photo",
        "class_type": "avatar",
        "category": "profile",
        "tags": "main,profile"
    }
)
print(res.json())

JavaScript

const form = new FormData();
form.append("file", fileInput.files[0]);
form.append("name", "Profile Photo");
form.append("class_type", "avatar");

const res = await fetch("/api/upload", {
  method: "POST",
  body: form
});
const data = await res.json();
console.log(data.url);

Error Responses

Status Error Cause
400 Content-Type must be multipart/form-data Wrong content type
400 No file provided Missing file field
400 name and class_type are required Missing required fields
413 File too large: ... bytes. Max: 10485760 bytes File exceeds 10 MB

Get / Update / Delete Profiles

Manage images by image ID or user ID.

Get Images

List images with optional filters.

GET /api/profiles

Parameters

Parameter Type Required Description
id string No Get a single image by ID
user_id string No Filter by user ID
class_type string No Filter by avatar or banner
category string No Filter by category
tags string No Comma-separated tags (AND logic)

Example

curl "https://openavaban-api.giripratik.com.np/api/profiles?class_type=avatar"

Response

[
  {
    "id": "64f1a2b3...",
    "name": "Profile Photo",
    "class_type": "avatar",
    "category": "profile",
    "url": "https://utfs.io/f/...",
    "tags": ["main"],
    ...
  }
]

Get Single Image

GET /api/profiles?id=<image_id>

curl "https://openavaban-api.giripratik.com.np/api/profiles?id=64f1a2b3..."

Update Image

Update an image's name, tags, category, or metadata.

PUT /api/profiles?id=<image_id>

Body (JSON)

Field Type Description
name string New display name
tags array New tags list
category string New category
class_type string avatar or banner
metadata object Custom metadata

Example

curl -X PUT "https://openavaban-api.giripratik.com.np/api/profiles?id=64f1a2b3..." \
  -H "Content-Type: application/json" \
  -d '{"name": "New Name", "tags": ["updated", "v2"]}'

Response

{
  "id": "64f1a2b3...",
  "name": "New Name",
  "tags": ["updated", "v2"],
  ...
}

Delete Image

Delete an image from the database and UploadThing.

DELETE /api/profiles?id=<image_id>

Example

curl -X DELETE "https://openavaban-api.giripratik.com.np/api/profiles?id=64f1a2b3..."

Response

{
  "success": true,
  "deleted": "64f1a2b3..."
}

Error Responses

Status Error Cause
400 id parameter is required Missing id in PUT/DELETE
404 Image not found Image doesn't exist

Random Image

Get one or more random images, optionally filtered by category. No API key required.

Endpoint

GET /api/random

Parameters

Parameter Type Required Default Description
category string No — Filter by category (partial match)
count integer No 1 Number of images (1-25)

Response

Single image (count=1)

{
  "id": "64f1a2b3...",
  "name": "Cute Avatar",
  "class_type": "avatar",
  "url": "https://utfs.io/f/...",
  ...
}

Multiple images (count>1)

[
  { "id": "...", "name": "...", "url": "..." },
  { "id": "...", "name": "...", "url": "..." }
]

Examples

Get a random avatar

curl "https://openavaban-api.giripratik.com.np/api/random?category=avatar"

Get 5 random images

curl "https://openavaban-api.giripratik.com.np/api/random?count=5"

Get random banner

curl "https://openavaban-api.giripratik.com.np/api/random?category=banner&count=3"

JavaScript Example

// Random image for a profile
async function getRandomAvatar() {
  const res = await fetch('/api/random?category=avatar');
  const image = res.json();
  return image.url;
}

Python Example

import requests

res = requests.get(
    "https://openavaban-api.giripratik.com.np/api/random",
    params={"category": "avatar", "count": 5}
)
images = res.json()

for img in images:
    print(img["url"])

Bulk Upload

Upload up to 100 images at once using a CSV file.

How It Works

  1. Download the CSV template
  2. Fill in each row with an image URL and metadata
  3. Upload the CSV to the bulk upload page
  4. All images are processed and added to your gallery

CSV Format

Column Required Description
file_url Yes Direct URL to the image file
name Yes Display name
class_type Yes avatar or banner
category No Category string
tags No Comma-separated tags

Template

Download the template from the bulk upload page.

Example content:

file_url,name,class_type,category,tags
https://example.com/photo1.jpg,Profile Photo,avatar,profile,"main,profile"
https://example.com/banner1.png,Social Banner,banner,social,"banner,v2"
https://example.com/photo2.png,Cute Avatar,avatar,profile,cute

Limits

  • Maximum 100 rows per CSV
  • Image files must be 10 MB or smaller
  • Supported formats: JPG, PNG, GIF, WebP
  • Images must be accessible via direct URL

Upload Page

Go to openavaban-api.giripratik.com.np/bulk to use the bulk upload form.

API Endpoint

POST /api/bulk

Headers

Header Required Description
Content-Type Yes multipart/form-data

Form Fields

Field Type Required Description
file CSV file Yes CSV with image URLs and metadata

Response

{
  "total": 50,
  "success": 48,
  "failed": 2,
  "results": [
    {"row": 1, "status": "ok", "url": "https://utfs.io/f/..."},
    {"row": 12, "status": "error", "error": "Failed to download image"},
    {"row": 37, "status": "error", "error": "Invalid file type"}
  ]
}

Python Example

import requests

files = {"file": open("images.csv", "rb")}

res = requests.post(
    "https://openavaban-api.giripratik.com.np/api/bulk",
    files=files
)
print(res.json())

JavaScript Example

const form = new FormData();
form.append("file", csvInput.files[0]);

const res = await fetch("/api/bulk", {
  method: "POST",
  body: form
});
const data = await res.json();
console.log(`${data.success} uploaded, ${data.failed} failed`);